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

Inheritance diagram for Picture:

[legend]

Public Member Functions
Result	load (const std::string &path) noexcept
	Loads a picture data directly from a file. More...

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

Result	load (const char *data, uint32_t size, const std::string &mimeType, bool copy=false) noexcept
	Loads a picture data from a memory block of a given size. More...

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

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

Result	load (uint32_t *data, uint32_t w, uint32_t h, bool copy) noexcept
	Loads a raw data from a memory block with a given size. More...

Result	mesh (const Polygon *triangles, uint32_t triangleCnt) noexcept
	Sets or removes the triangle mesh to deform the image. More...

uint32_t	mesh (const Polygon **triangles) const noexcept
	Return the number of triangles in the mesh, and optionally get a pointer to the array of triangles in the mesh. 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	blend (BlendMethod method) const noexcept
	Sets the blending method for the paint object. More...

TVG_DEPRECATED Result	bounds (float x, float y, float w, float h) const noexcept
	Gets the bounding box of the paint object before any transformation. More...

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

BlendMethod	blend () const noexcept
	Gets the blending method of the object. More...

uint32_t	identifier () const noexcept
	Return the unique id value of the paint instance. More...

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

static uint32_t	identifier () noexcept
	Return the unique id value of this class. More...

Detailed Description

A class representing an image read in one of the supported formats: raw, svg, png, jpg, lottie(json) 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.

Member Function Documentation

◆ gen()

static std::unique_ptr<Picture> gen ( )

staticnoexcept

Creates a new Picture object.

Returns: A new Picture object.

◆ identifier()

static uint32_t identifier ( )

staticnoexcept

Return the unique id value of this class.

This method can be referred for identifying the Picture class type.

Returns: The type id of the Picture class.

◆ load() [1/4]

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

noexcept

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

Parameters

[in]	data	A pointer to a memory location where the content of the picture file is stored.
[in]	size	The size in bytes of the memory occupied by the `data`.
[in]	copy	Decides whether the data should be copied into the engine local buffer.

Return values

Result::Success	When succeed.
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.
Result::Unknown	If an error occurs at a later stage.

Warning: : you have responsibility to release the data memory if the copy is true

See also: Result load(const char* data, uint32_t size, const std::string& mimeType, bool copy = false) noexcept

◆ load() [2/4]

Result load	(	const char *	data,
		uint32_t	size,
		const std::string &	mimeType,
		bool	copy = `false`
	)

noexcept

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

Parameters

[in]	data	A pointer to a memory location where the content of the picture file is stored.
[in]	size	The size in bytes of the memory occupied by the `data`.
[in]	mimeType	Mimetype or extension of data such as "jpg", "jpeg", "lottie", "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]	copy	If `true` the data are copied into the engine local buffer, otherwise they are not.

Return values

Result::Success	When succeed.
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.
Result::Unknown	If an error occurs at a later stage.

Warning: : It's the user responsibility to release the data memory if the copy is true.

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

Since: 0.5

◆ load() [3/4]

Result load ( const std::string & path )

noexcept

Loads a picture data directly from a file.

Parameters

[in] path A path to the picture file.

Return values

Result::Success	When succeed.
Result::InvalidArguments	In case the `path` is invalid.
Result::NonSupport	When trying to load a file with an unknown extension.
Result::Unknown	If an error occurs at a later stage.

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

See also: Initializer::init()

◆ load() [4/4]

Result load	(	uint32_t *	data,
		uint32_t	w,
		uint32_t	h,
		bool	copy
	)

noexcept

Loads a raw data from a memory block with a given size.

Return values

Result::Success	When succeed, Result::InsufficientCondition otherwise.
Result::FailedAllocation	An internal error possibly with memory allocation.

Since: 0.9

◆ mesh() [1/2]

uint32_t mesh ( const Polygon ** triangles ) const

noexcept

Return the number of triangles in the mesh, and optionally get a pointer to the array of triangles in the mesh.

Parameters

[out] triangles Optional. A pointer to the array of Polygons used by this mesh.

Returns: uint32_t The number of polygons in the array.

Note: Modifying the triangles returned by this method will modify them directly within the mesh.

Warning: Please do not use it, this API is not official one. It could be modified in the next version.

@BETA_API

◆ mesh() [2/2]

Result mesh	(	const Polygon *	triangles,
		uint32_t	triangleCnt
	)

noexcept

Sets or removes the triangle mesh to deform the image.

If a mesh is provided, the transform property of the Picture will apply to the triangle mesh, and the image data will be used as the texture.

If triangles is nullptr, or triangleCnt is 0, the mesh will be removed.

Only raster image types are supported at this time (png, jpg). Vector types like svg and tvg do not support. mesh deformation. However, if required you should be able to render a vector image to a raster image and then apply a mesh.

Parameters

[in]	triangles	An array of Polygons(triangles) that make up the mesh, or null to remove the mesh.
[in]	triangleCnt	The number of Polygons(triangles) provided, or 0 to remove the mesh.

Return values

Result::Success	When succeed.
Result::Unknown	If fails

Note: The Polygons are copied internally, so modifying them after calling Mesh::mesh has no affect.

Warning: Please do not use it, this API is not official one. It could be modified in the next version.

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

Returns: Result::Success when succeed.

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

Returns: Result::Success when succeed, Result::InsufficientCondition otherwise.

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ gen()

◆ identifier()

◆ load() [1/4]

◆ load() [2/4]

◆ load() [3/4]

◆ load() [4/4]

◆ mesh() [1/2]

◆ mesh() [2/2]

◆ size() [1/2]

◆ size() [2/2]