# ThorVG: Picture

Picturefinal
ThorVG

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]
Collaboration 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
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 raw data in ARGB8888 format from a memory block of the given size. More...
const Paint * | paint (uint32_t id) noexcept
| Retrieve a paint object from the Picture scene by its Unique ID. 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< Picture > | gen () noexcept
| Creates a new Picture 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 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 TVG_DEPRECATED uint32_t identifier | ( |  | ) |

staticnoexcept

See also
  Picture::type()

## load() [1/4]

TVG_DEPRECATED Result load | ( | const char * | data,
|  | uint32_t | size,
|  | 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.

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", "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::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 `""`, 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.

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] | path | A path to 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() [4/4]

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

noexcept

Loads raw data in ARGB8888 format from a memory block of the 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 raw data is stored.
  [in] | w | The width of the image `data` in pixels.
  [in] | h | The height of the image `data` in pixels.
  [in] | premultiplied | If `true`, the given image data is alpha-premultiplied.
  [in] | copy | If `true` the data are copied into the engine local buffer, otherwise they are not.

Since
  0.9

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

Note
  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
  Experimental API

Implements Paint.