An abstract class for managing graphical elements. More...

#include <thorvg.h>

Inheritance diagram for Paint:

[legend]

Public Member Functions
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.

virtual Type	type () const noexcept=0
	Returns the ID value of this class.

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

Public Attributes
uint32_t	id = 0
	Unique ID of this instance.

Detailed Description

An abstract class for managing graphical elements.

A graphical element in TVG is any object composed into a Canvas. Paint represents such a graphical object and its behaviors such as duplication, transformation and composition. TVG recommends the user to regard a paint as a set of volatile commands. They can prepare a Paint and then request a Canvas to run them.

Member Function Documentation

◆ blend()

Result blend ( BlendMethod method )

noexcept

Sets the blending method for the paint object.

The blending feature allows you to combine colors to create visually appealing effects, including transparency, lighting, shading, and color mixing, among others. its process involves the combination of colors or images from the source paint object with the destination (the lower layer image) using blending operations. The blending operation is determined by the chosen BlendMethod, which specifies how the colors or images are combined.

Parameters

[in] method The blending method to be set.

Since: 1.0

◆ bounds() [1/2]

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.

Returns the bounding box of the paint as an axis-aligned bounding box (AABB), with all relevant transformations applied. The returned values x, y, w, h, may have invalid if the operation fails. Thus, please check the retval.

This bounding box can be used to determine the actual rendered area of the object on the canvas, for purposes such as hit-testing, culling, or layout calculations.

Parameters

[out]	x	The x-coordinate of the upper-left corner of the bounding box.
[out]	y	The y-coordinate of the upper-left corner of the bounding box.
[out]	w	The width of the bounding box.
[out]	h	The height of the bounding box.

Return values

Result::InsufficientCondition If the paint has not been updated by the canvas.

See also: Paint::bounds(Point* pt4); Canvas::update()

◆ bounds() [2/2]

Result bounds ( Point * pt4 )

noexcept

Retrieves the object-oriented bounding box (OBB) of the paint object in canvas space.

This function returns the bounding box of the paint, as an oriented bounding box (OBB) after transformations are applied. The returned values pt4 may have invalid if the operation fails. Thus, please check the retval.

This bounding box can be used to obtain the transformed bounding region in canvas space by taking the geometry's axis-aligned bounding box (AABB) in the object's local coordinate space and applying the object's transformations.

Parameters

[out] pt4 An array of four points representing the bounding box. The array size must be 4.

Return values

Result::InsufficientCondition If the paint has not been updated by the canvas.

See also: Paint::bounds(float* x, float* y, float* w, float* h); Canvas::update()

Since: 1.0

◆ clip() [1/2]

Shape * clip ( ) const

noexcept

Get the clipper shape of the paint object.

This function returns the clipper that has been previously set to this paint object.

Returns: The shape object used as the clipper, or nullptr if no clipper is set.

See also: Paint::clip(Shape* clipper)

Since: 1.0

◆ clip() [2/2]

Result clip ( Shape * clipper )

noexcept

Clip the drawing region of the paint object.

This function restricts the drawing area of the paint object to the specified shape's paths.

Parameters

[in] clipper The shape object as the clipper.

Return values

Result::InsufficientCondition if the clipper has already belonged to another paint.

See also: Paint::clip()

Since: 1.0

◆ duplicate()

Paint * duplicate ( ) const

noexcept

Duplicates the object.

Creates a new object and sets its all properties as in the original object.

Returns: The created object when succeed, nullptr otherwise.

◆ intersects()

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.

This function determines whether the specified rectangular region—defined by (x, y, w, h)— intersects the geometric fill region of the paint object.

This is useful for hit-testing purposes, such as detecting whether a user interaction (e.g., touch or click) occurs within a painted region.

The paint must be updated in a Canvas beforehand—typically after the Canvas has been drawn and synchronized.

Parameters

[in]	x	The x-coordinate of the top-left corner of the test region.
[in]	y	The y-coordinate of the top-left corner of the test region.
[in]	w	The width of the region to test. Must be greater than 0; defaults to 1.
[in]	h	The height of the region to test. Must be greater than 0; defaults to 1.

Returns: true if any part of the region intersects the filled area; otherwise, false.

Note: To test a single point, set the region size to w = 1, h = 1.; For efficiency, an AABB (axis-aligned bounding box) test is performed internally before precise hit detection.; This test does not take into account the results of blending or masking.; This test does take into account the the hidden paints as well.

See also: Paint::visible()

Since: 1.0

◆ mask() [1/2]

MaskMethod mask ( const Paint ** target ) const

noexcept

Gets the masking target object and the masking method.

Parameters

[out] target The paint of the target object.

Returns: The method used to mask the source object with the target.

Since: 0.5

◆ mask() [2/2]

Result mask	(	Paint *	target,
		MaskMethod	method
	)

noexcept

Sets the masking target object and the masking method.

Parameters

[in]	target	The paint of the target object.
[in]	method	The method used to mask the source object with the target.

Return values

Result::InsufficientCondition	if the target has already belonged to another paint.
Result::InvalidArguments	`method` equals `MaskMethod::None` and `target` is not `nullptr`.

◆ opacity() [1/2]

uint8_t opacity ( ) const

noexcept

Gets the opacity value of the object.

Returns: The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

◆ opacity() [2/2]

Result opacity ( uint8_t o )

noexcept

Sets the opacity of the object.

Parameters

[in] o The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Note: Setting the opacity with this API may require multiple render pass for composition. It is recommended to avoid changing the opacity if possible.

◆ parent()

const Paint * parent ( ) const

noexcept

Retrieves the parent paint object.

This function returns a pointer to the parent object if the current paint belongs to one. Otherwise, it returns nullptr.

Returns: A pointer to the parent object if available, otherwise nullptr.

See also: Scene::push(); Canvas::push()

Since: 1.0

◆ ref()

uint16_t ref ( )

noexcept

Increment the reference count for the Paint instance.

This method increases the reference count of the Paint object, allowing shared ownership and control over its lifetime.

Returns: The updated reference count after the increment by 1.

Warning: Please ensure that each call to ref() is paired with a corresponding call to unref() to prevent a dangling instance.

See also: Paint::unref(); Paint::refCnt()

Since: 1.0

◆ refCnt()

uint16_t refCnt ( ) const

noexcept

Retrieve the current reference count of the Paint instance.

This method provides the current reference count, allowing the user to check the shared ownership state of the Paint object.

Returns: The current reference count of the Paint instance.

See also: Paint::ref(); Paint::unref()

Since: 1.0

◆ rel()

static void rel ( Paint * paint )

staticnoexcept

Safely releases a Paint object.

This is the counterpart to the gen() API, and releases the given Paint object safely, handling nullptr and managing ownership properly.

Parameters

[in] paint A Paint object to release.

Since: 1.0

◆ rotate()

Result rotate ( float degree )

noexcept

Sets the angle by which the object is rotated.

The angle in measured clockwise from the horizontal axis. The rotational axis passes through the point on the object with zero coordinates.

Parameters

[in] degree The value of the angle in degrees.

Return values

Result::InsufficientCondition in case a custom transform is applied.

See also: Paint::transform()

◆ scale()

Result scale ( float factor )

noexcept

Sets the scale value of the object.

Parameters

[in] factor The value of the scaling factor. The default value is 1.

Return values

Result::InsufficientCondition in case a custom transform is applied.

See also: Paint::transform()

◆ transform() [1/2]

Matrix & transform ( )

noexcept

Gets the matrix of the affine transformation of the object.

The values of the matrix can be set by the transform() API, as well by the translate(), scale() and rotate(). In case no transformation was applied, the identity matrix is returned.

Returns: The augmented transformation matrix.

Since: 0.4

◆ transform() [2/2]

Result transform ( const Matrix & m )

noexcept

Sets the matrix of the affine transformation for the object.

The augmented matrix of the transformation is expected to be given.

Parameters

[in] m The 3x3 augmented matrix.

◆ translate()

Result translate	(	float	x,
		float	y
	)

noexcept

Sets the values by which the object is moved in a two-dimensional space.

The origin of the coordinate system is in the upper-left corner of the canvas. The horizontal and vertical axes point to the right and down, respectively.

Parameters

[in]	x	The value of the horizontal shift.
[in]	y	The value of the vertical shift.

Return values

Result::InsufficientCondition in case a custom transform is applied.

See also: Paint::transform()

◆ type()

virtual Type type ( ) const

pure virtualnoexcept

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

Since: 1.0

Implemented in Shape, Picture, Scene, and Text.

◆ unref()

uint16_t unref ( bool free = true )

noexcept

Decrement the reference count for the Paint instance.

This method decreases the reference count of the Paint object by 1. If the reference count reaches zero and the free flag is set to true, the Paint instance is automatically deleted.

Parameters

[in] free Flag indicating whether to delete the Paint instance when the reference count reaches zero.

Returns: The updated reference count after the decrement.

See also: Paint::ref(); Paint::refCnt()

Since: 1.0

◆ visible() [1/2]

bool visible ( ) const

noexcept

Gets the current visibility status of the Paint object.

Returns: true if the object is visible and will be rendered. false if the object is hidden and will not be rendered.

See also: Paint::visible(bool on)

Since: 1.0

◆ visible() [2/2]

Result visible ( bool on )

noexcept

Sets the visibility of the Paint object.

This is useful for selectively excluding paint objects during rendering.

Parameters

[in] on A boolean flag indicating visibility. The default is true. true, the object will be rendered by the engine. false, the object will be excluded from the drawing process.

Note: An invisible object is not considered inactive—it may still participate in internal update processing if its properties are updated, but it will not be taken into account for the final drawing output. To completely deactivate a paint object, remove it from the canvas.

See also: Paint::visible() const; Result Canvas::remove(Paint* paint)

Since: 1.0

Member Data Documentation

◆ id

uint32_t id = 0

Unique ID of this instance.

This is reserved to specify an paint instance in a scene.

Since: 1.0

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ blend()

◆ bounds() [1/2]

◆ bounds() [2/2]

◆ clip() [1/2]

◆ clip() [2/2]

◆ duplicate()

◆ intersects()

◆ mask() [1/2]

◆ mask() [2/2]

◆ opacity() [1/2]

◆ opacity() [2/2]

◆ parent()

◆ ref()

◆ refCnt()

◆ rel()

◆ rotate()

◆ scale()

◆ transform() [1/2]

◆ transform() [2/2]

◆ translate()

◆ type()

◆ unref()

◆ visible() [1/2]

◆ visible() [2/2]

Member Data Documentation

◆ id