A class representing an image read in one of the supported formats: raw, svg, png, jpg, lot and etc. Besides the methods inherited from the Paint, it provides methods to load & draw images on the canvas. More...

#include <thorvg.h>

Inheritance diagram for Picture:

[legend]

Collaboration diagram for Picture:

[legend]

Public Member Functions
Result	load (const char *filename) noexcept
	Loads a picture data directly from a file.

Result	load (const char data, uint32_t size, const char mimeType, const char *rpath=nullptr, bool copy=false) noexcept
	Loads a picture data from a memory block of a given size.

Result	size (float w, float h) noexcept
	Resizes the picture content to the given width and height.

Result	size (float w, float h) const noexcept
	Gets the size of the image.

Result	origin (float x, float y) noexcept
	Sets the normalized origin point of the Picture object.

Result	origin (float x, float y) const noexcept
	Gets the normalized origin point of the Picture object.

Result	load (const uint32_t *data, uint32_t w, uint32_t h, ColorSpace cs, bool copy=false) noexcept
	Loads raw image data in a specific format from a memory block of the given size.

Result	resolver (std::function< bool(Paint paint, const char src, void data)> func, void data) noexcept
	Sets the asset resolver callback for handling external resources (e.g., images and fonts).

const Paint *	paint (uint32_t id) noexcept
	Retrieve a paint object from the Picture scene by its Unique ID.

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 Picture *	gen () noexcept
	Creates a new Picture 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 an image read in one of the supported formats: raw, svg, png, jpg, lot and etc. Besides the methods inherited from the Paint, it provides methods to load & draw images on the canvas.

Note: Supported formats are depended on the available TVG loaders.; See Animation class if the picture data is animatable.

Warning: This class is not designed for inheritance.

Member Function Documentation

◆ gen()

static Picture * gen ( )

staticnoexcept

Creates a new Picture object.

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

Returns: A pointer to the newly created Picture object.

See also: Paint::rel()

◆ load() [1/3]

Result load	(	const char *	data,
		uint32_t	size,
		const char *	mimeType,
		const char *	rpath = `nullptr`,
		bool	copy = `false`
	)

noexcept

Loads a picture data from a memory block of a given size.

ThorVG efficiently caches the loaded data using the specified data address as a key when the copy has false. This means that loading the same data again will not result in duplicate operations for the sharable data. Instead, ThorVG will reuse the previously loaded picture data.

Parameters

[in]	data	A pointer to a memory location where the content of the picture file is stored. A null-terminated string is expected for non-binary data if `copy` is `false`.
[in]	size	The size in bytes of the memory occupied by the `data`.
[in]	mimeType	Mimetype or extension of data such as "jpg", "jpeg", "lot", "lottie+json", "svg", "svg+xml", "png", etc. In case an empty string or an unknown type is provided, the loaders will be tried one by one.
[in]	rpath	A resource directory path, if the `data` needs to access any external resources.
[in]	copy	If `true` the data are copied into the engine local buffer, otherwise they are not.

Return values

Result::InvalidArguments	In case no data are provided or the `size` is zero or less.
Result::NonSupport	When trying to load a file with an unknown extension.

Warning: It's the user responsibility to release the data memory.

Note: If you are unsure about the MIME type, you can provide an empty value like nullptr, and thorvg will attempt to figure it out.

Since: 0.5

◆ load() [2/3]

Result load ( const char * filename )

noexcept

Loads a picture data directly from a file.

ThorVG efficiently caches the loaded data using the specified path as a key. This means that loading the same file again will not result in duplicate operations; instead, ThorVG will reuse the previously loaded picture data.

Parameters

[in] filename A file name, including the path, for the picture file.

Return values

Result::InvalidArguments	In case the `path` is invalid.
Result::NonSupport	When trying to load a file with an unknown extension.

Note: The Load behavior can be asynchronous if the assigned thread number is greater than zero.

See also: Initializer::init()

◆ load() [3/3]

Result load	(	const uint32_t *	data,
		uint32_t	w,
		uint32_t	h,
		ColorSpace	cs,
		bool	copy = `false`
	)

noexcept

Loads raw image data in a specific format from a memory block of the given size.

ThorVG efficiently caches the loaded data, using the provided data address as a key when copy is set to false. This allows ThorVG to avoid redundant operations by reusing the previously loaded picture data for the same sharable data, rather than duplicating the load process.

Parameters

[in]	data	A pointer to the memory block where the raw image data is stored.
[in]	w	The width of the image in pixels.
[in]	h	The height of the image in pixels.
[in]	cs	Specifies how the 32-bit color values should be interpreted.
[in]	copy	If `true`, the data is copied into the engine's local buffer. If `false`, the data is not copied.

Since: 0.9

◆ origin() [1/2]

Result origin	(	float *	x,
		float *	y
	)		const

noexcept

Gets the normalized origin point of the Picture object.

This method retrieves the current origin point of the Picture, expressed in normalized coordinates relative to the picture’s bounds.

Parameters

[out]	x	The normalized x-coordinate of the origin (range: 0.0f to 1.0f).
[out]	y	The normalized y-coordinate of the origin (range: 0.0f to 1.0f).

See also: origin()

Since: 1.0

◆ origin() [2/2]

Result origin	(	float	x,
		float	y
	)

noexcept

Sets the normalized origin point of the Picture object.

This method defines the origin point of the Picture using normalized coordinates. Unlike a typical pivot point used only for transformations, this origin affects both the transformation behavior and the actual rendering position of the Picture.

The specified origin becomes the reference point for positioning the Picture on the canvas. For example, setting the origin to (0.5f, 0.5f) moves the visual center of the picture to the position specified by Paint::translate().

The coordinates are given in a normalized range relative to the picture's bounds:

(0.0f, 0.0f): top-left corner
(0.5f, 0.5f): center
(1.0f, 1.0f): bottom-right corner

Parameters

[in]	x	The normalized x-coordinate of the origin point (range: 0.0f to 1.0f).
[in]	y	The normalized y-coordinate of the origin point (range: 0.0f to 1.0f).

Note: This origin directly affects how the Picture is placed on the canvas when using transformations such as translate(), rotate(), or scale().

See also: Paint::translate(); Paint::rotate(); Paint::scale()

Since: 1.0

◆ paint()

const Paint * paint ( uint32_t id )

noexcept

Retrieve a paint object from the Picture scene by its Unique ID.

This function searches for a paint object within the Picture scene that matches the provided id.

Parameters

[in] id The Unique ID of the paint object.

Returns: A pointer to the paint object that matches the given identifier, or nullptr if no matching paint object is found.

See also: Accessor::id()

Since: 1.0

◆ resolver()

Result resolver	(	std::function< bool(Paint paint, const char src, void *data)>	func,
		void *	data
	)

noexcept

Sets the asset resolver callback for handling external resources (e.g., images and fonts).

This callback is invoked when an external asset reference (such as an image source or file path) is encountered in a Picture object. It allows the user to provide a custom mechanism for loading or substituting assets, such as loading from an external source or a virtual filesystem.

Parameters

[in]	func	A user-defined function that handles the resolution of asset paths. `resolver` can return `true` if the asset was successfully resolved by the user, or `false` if it was not.
[in]	data	A pointer to user-defined data that will be passed to the callback each time it is invoked. This can be used to maintain context or access external resources.

Return values

Result::InsufficientCondition If the picture is already loaded.

Note: This function must be called before Picture::load() Setting the resolver after loading will have no effect on asset resolution for that asset.; If false is returned by func, ThorVG will attempt to resolve the resource using its internal resolution mechanism as a fallback.; To unset the resolver, pass nullptr as the func parameter.; Experimental API

◆ size() [1/2]

Result size	(	float *	w,
		float *	h
	)		const

noexcept

Gets the size of the image.

Parameters

[out]	w	The width of the image in pixels.
[out]	h	The height of the image in pixels.

◆ size() [2/2]

Result size	(	float	w,
		float	h
	)

noexcept

Resizes the picture content to the given width and height.

The picture content is resized while keeping the default size aspect ratio. The scaling factor is established for each of dimensions and the smaller value is applied to both of them.

Parameters

[in]	w	A new width of the image in pixels.
[in]	h	A new height of the image in pixels.

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

Since: 1.0

Implements Paint.

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ gen()

◆ load() [1/3]

◆ load() [2/3]

◆ load() [3/3]

◆ origin() [1/2]

◆ origin() [2/2]

◆ paint()

◆ resolver()

◆ size() [1/2]

◆ size() [2/2]

◆ type()