thorvg.h

Defines

TVG_BUILD
TVG_API
TVG_DEPRECATED
_TVG_DECLARE_PRIVATE(A)
_TVG_DISABLE_CTOR(A)
_TVG_DECLARE_ACCESSOR(A)
namespace tvg

Enums

enum class Result

Enumeration specifying the result from the APIs.

Values:

enumerator Success

The value returned in case of a correct request execution.

enumerator InvalidArguments

The value returned in the event of a problem with the arguments given to the API - e.g. empty paths or null pointers.

enumerator InsufficientCondition

The value returned in case the request cannot be processed - e.g. asking for properties of an object, which does not exist.

enumerator FailedAllocation

The value returned in case of unsuccessful memory allocation.

enumerator MemoryCorruption

The value returned in the event of bad memory handling - e.g. failing in pointer releasing or casting.

enumerator NonSupport

The value returned in case of choosing unsupported options.

enumerator Unknown

The value returned in all other cases.

enum class PathCommand

Enumeration specifying the values of the path commands accepted by TVG.

Not to be confused with the path commands from the svg path element (like M, L, Q, H and many others). TVG interprets all of them and translates to the ones from the PathCommand values.

Values:

enumerator Close

Ends the current sub-path and connects it with its initial point. This command doesn't expect any points.

enumerator MoveTo

Sets a new initial point of the sub-path and a new current point. This command expects 1 point: the starting position.

enumerator LineTo

Draws a line from the current point to the given point and sets a new value of the current point. This command expects 1 point: the end-position of the line.

enumerator CubicTo

Draws a cubic Bezier curve from the current point to the given point using two given control points and sets a new value of the current point. This command expects 3 points: the 1st control-point, the 2nd control-point, the end-point of the curve.

enum class StrokeCap

Enumeration determining the ending type of a stroke in the open sub-paths.

Values:

enumerator Square

The stroke is extended in both end-points of a sub-path by a rectangle, with the width equal to the stroke width and the length equal to the half of the stroke width. For zero length sub-paths the square is rendered with the size of the stroke width.

enumerator Round

The stroke is extended in both end-points of a sub-path by a half circle, with a radius equal to the half of a stroke width. For zero length sub-paths a full circle is rendered.

enumerator Butt

The stroke ends exactly at each of the two end-points of a sub-path. For zero length sub-paths no stroke is rendered.

enum class StrokeJoin

Enumeration determining the style used at the corners of joined stroked path segments.

Values:

enumerator Bevel

The outer corner of the joined path segments is bevelled at the join point. The triangular region of the corner is enclosed by a straight line between the outer corners of each stroke.

enumerator Round

The outer corner of the joined path segments is rounded. The circular region is centered at the join point.

enumerator Miter

The outer corner of the joined path segments is spiked. The spike is created by extension beyond the join point of the outer edges of the stroke until they intersect. In case the extension goes beyond the limit, the join style is converted to the Bevel style.

enum class FillSpread

Enumeration specifying how to fill the area outside the gradient bounds.

Values:

enumerator Pad

The remaining area is filled with the closest stop color.

enumerator Reflect

The gradient pattern is reflected outside the gradient area until the expected region is filled.

enumerator Repeat

The gradient pattern is repeated continuously beyond the gradient area until the expected region is filled.

enum class FillRule

Enumeration specifying the algorithm used to establish which parts of the shape are treated as the inside of the shape.

Values:

enumerator Winding

A line from the point to a location outside the shape is drawn. The intersections of the line with the path segment of the shape are counted. Starting from zero, if the path segment of the shape crosses the line clockwise, one is added, otherwise one is subtracted. If the resulting sum is non zero, the point is inside the shape.

enumerator EvenOdd

A line from the point to a location outside the shape is drawn and its intersections with the path segments of the shape are counted. If the number of intersections is an odd number, the point is inside the shape.

enum class CompositeMethod

Enumeration indicating the method used in the composition of two objects - the target and the source.

Notation: S(Source), T(Target), SA(Source Alpha), TA(Target Alpha)

See also

Paint::composite()

Values:

enumerator None

No composition is applied.

enumerator ClipPath

The intersection of the source and the target is determined and only the resulting pixels from the source are rendered.

enumerator AlphaMask

Alpha Masking using the compositing target's pixels as an alpha value.

enumerator InvAlphaMask

Alpha Masking using the complement to the compositing target's pixels as an alpha value.

enumerator LumaMask

Alpha Masking using the grayscale (0.2125R + 0.7154G + 0.0721*B) of the compositing target's pixels.

Since

0.9

enumerator InvLumaMask

Alpha Masking using the grayscale (0.2125R + 0.7154G + 0.0721*B) of the complement to the compositing target's pixels.

enumerator AddMask

Combines the target and source objects pixels using target alpha. (T * TA) + (S * (255 - TA)) (Experimental API)

enumerator SubtractMask

Subtracts the source color from the target color while considering their respective target alpha. (T * TA) - (S * (255 - TA)) (Experimental API)

enumerator IntersectMask

Computes the result by taking the minimum value between the target alpha and the source alpha and multiplies it with the target color. (T * min(TA, SA)) (Experimental API)

enumerator DifferenceMask

Calculates the absolute difference between the target color and the source color multiplied by the complement of the target alpha. abs(T - S * (255 - TA)) (Experimental API)

enum class BlendMethod : uint8_t

Enumeration indicates the method used for blending paint. Please refer to the respective formulas for each method.

Notation: S(source paint as the top layer), D(destination as the bottom layer), Sa(source paint alpha), Da(destination alpha)

See also

Paint::blend()

Note

Experimental API

Values:

enumerator Normal

Perform the alpha blending(default). S if (Sa == 255), otherwise (Sa * S) + (255 - Sa) * D.

enumerator Add

Simply adds pixel values of one layer with the other. (S + D)

enumerator Screen

The values of the pixels in the two layers are inverted, multiplied, and then inverted again. (S + D) - (S * D)

enumerator Multiply

Takes the RGB channel values from 0 to 255 of each pixel in the top layer and multiples them with the values for the corresponding pixel from the bottom layer. (S * D)

enumerator Overlay

Combines Multiply and Screen blend modes. (2 * S * D) if (2 * D < Da), otherwise (Sa * Da) - 2 * (Da - S) * (Sa - D)

enumerator Difference

Subtracts the bottom layer from the top layer or the other way around, to always get a non-negative value. (S - D) if (S > D), otherwise (D - S)

enumerator Exclusion

The result is twice the product of the top and bottom layers, subtracted from their sum. s + d - (2 * s * d)

enumerator SrcOver

Replace the bottom layer with the top layer.

enumerator Darken

Creates a pixel that retains the smallest components of the top and bottom layer pixels. min(S, D)

enumerator Lighten

Only has the opposite action of Darken Only. max(S, D)

enumerator ColorDodge

Divides the bottom layer by the inverted top layer. D / (255 - S)

enumerator ColorBurn

Divides the inverted bottom layer by the top layer, and then inverts the result. 255 - (255 - D) / S.

enumerator HardLight

The same as Overlay but with the color roles reversed. (2 * S * D) if (S < Sa), otherwise (Sa * Da) - 2 * (Da - S) * (Sa - D)

enumerator SoftLight

The same as Overlay but with applying pure black or white does not result in pure black or white. (1 - 2 * S) * (D ^ 2) + (2 * S * D)

enum class CanvasEngine

Enumeration specifying the engine type used for the graphics backend. For multiple backends bitwise operation is allowed.

Values:

enumerator Sw

CPU rasterizer.

enumerator Gl

OpenGL rasterizer.

enumerator Wg

WebGPU rasterizer. (Experimental API)

Functions

template<typename T = tvg::Paint>
std::unique_ptr<T> cast(Paint *paint)

The cast() function is a utility function used to cast a 'Paint' to type 'T'.

Since

0.11

template<typename T = tvg::Fill>
std::unique_ptr<T> cast(Fill *fill)

The cast() function is a utility function used to cast a 'Fill' to type 'T'.

Since

0.11

struct Point
#include <thorvg.h>

A data structure representing a point in two-dimensional space.

Public Members

float x
float y
struct Matrix
#include <thorvg.h>

A data structure representing a three-dimensional matrix.

The elements e11, e12, e21 and e22 represent the rotation matrix, including the scaling factor. The elements e13 and e23 determine the translation of the object along the x and y-axis, respectively. The elements e31 and e32 are set to 0, e33 is set to 1.

Public Members

float e11
float e12
float e13
float e21
float e22
float e23
float e31
float e32
float e33
struct Vertex
#include <thorvg.h>

A data structure representing a texture mesh vertex.

Note

Experimental API

Param pt:

The vertex coordinate

Param uv:

The normalized texture coordinate in the range (0.0..1.0, 0.0..1.0)

Public Members

Point pt
Point uv
struct Polygon
#include <thorvg.h>

A data structure representing a triangle in a texture mesh.

Note

Experimental API

Param vertex:

The three vertices that make up the polygon

Public Members

Vertex vertex[3]
class Paint
#include <thorvg.h>

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.

Subclassed by tvg::Picture, tvg::Scene, tvg::Shape, tvg::Text

Public Functions

virtual ~Paint()
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:

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

Return values:

Result::Success -- when succeed, Result::FailedAllocation otherwise.

Result scale(float factor) noexcept

Sets the scale value of the object.

Parameters:

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

Return values:

Result::Success -- when succeed, Result::FailedAllocation otherwise.

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:

  • x -- [in] The value of the horizontal shift.

  • y -- [in] The value of the vertical shift.

Return values:

Result::Success -- when succeed, Result::FailedAllocation otherwise.

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:

m -- [in] The 3x3 augmented matrix.

Return values:

Result::Success -- when succeed, Result::FailedAllocation otherwise.

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.

Since

0.4

Returns:

The augmented transformation matrix.

Result opacity(uint8_t o) noexcept

Sets the opacity of the object.

Note

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

Note

ClipPath won't use the opacity value. (see: enum class CompositeMethod::ClipPath)

Parameters:

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

Return values:

Result::Success -- when succeed.

Result composite(std::unique_ptr<Paint> target, CompositeMethod method) noexcept

Sets the composition target object and the composition method.

Parameters:

  • target -- [in] The paint of the target object.

  • method -- [in] The method used to composite the source object with the target.

Return values:

Result::Success -- when succeed, Result::InvalidArguments otherwise.

Result blend(BlendMethod method) const 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.

Note

Experimental API

Parameters:

method -- [in] The blending method to be set.

Return values:

Result::Success -- when the blending method is successfully set.

Result bounds(float *x, float *y, float *w, float *h) const noexcept

Gets the bounding box of the paint object before any transformation.

Deprecated:

Use bounds(float* x, float* y, float* w, float* h, bool transformed) instead

See also

Paint::bounds(float* x, float* y, float* w, float* h, bool transformed);

Note

The bounding box doesn't indicate the final rendered region. It's the smallest rectangle that encloses the object.

Parameters:

  • x -- [out] The x coordinate of the upper left corner of the object.

  • y -- [out] The y coordinate of the upper left corner of the object.

  • w -- [out] The width of the object.

  • h -- [out] The height of the object.

Returns:

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

Result bounds(float *x, float *y, float *w, float *h, bool transformed) const noexcept

Gets the axis-aligned bounding box of the paint object.

In case transform is true, all object's transformations are applied first, and then the bounding box is established. Otherwise, the bounding box is determined before any transformations.

Note

The bounding box doesn't indicate the actual drawing region. It's the smallest rectangle that encloses the object.

Parameters:

  • x -- [out] The x coordinate of the upper left corner of the object.

  • y -- [out] The y coordinate of the upper left corner of the object.

  • w -- [out] The width of the object.

  • h -- [out] The height of the object.

  • transformed -- [in] If true, the paint's transformations are taken into account, otherwise they aren't.

Return values:

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

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.

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.

CompositeMethod composite(const Paint **target) const noexcept

Gets the composition target object and the composition method.

Since

0.5

Parameters:

target -- [out] The paint of the target object.

Returns:

The method used to composite the source object with the target.

BlendMethod blend() const noexcept

Gets the blending method of the object.

Note

Experimental API

Returns:

The blending method

uint32_t identifier() const noexcept

Return the unique id value of the paint instance.

This method can be called for checking the current concrete instance type.

Returns:

The type id of the Paint instance.

Public Members

Impl *pImpl

Protected Functions

Paint(const Paint&) = delete
const Paint &operator=(const Paint&) = delete
Paint()
class Fill
#include <thorvg.h>

An abstract class representing the gradient fill of the Shape object.

It contains the information about the gradient colors and their arrangement inside the gradient bounds. The gradients bounds are defined in the LinearGradient or RadialGradient class, depending on the type of the gradient to be used. It specifies the gradient behavior in case the area defined by the gradient bounds is smaller than the area to be filled.

Subclassed by tvg::LinearGradient, tvg::RadialGradient

Public Functions

virtual ~Fill()
Result colorStops(const ColorStop *colorStops, uint32_t cnt) noexcept

Sets the parameters of the colors of the gradient and their position.

Parameters:

  • colorStops -- [in] An array of ColorStop data structure.

  • cnt -- [in] The count of the colorStops array equal to the colors number used in the gradient.

Return values:

Result::Success -- when succeed.

Result spread(FillSpread s) noexcept

Sets the FillSpread value, which specifies how to fill the area outside the gradient bounds.

Parameters:

s -- [in] The FillSpread value.

Return values:

Result::Success -- when succeed.

Result transform(const Matrix &m) noexcept

Sets the matrix of the affine transformation for the gradient fill.

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

Parameters:

m -- [in] The 3x3 augmented matrix.

Return values:

Result::Success -- when succeed, Result::FailedAllocation otherwise.

uint32_t colorStops(const ColorStop **colorStops) const noexcept

Gets the parameters of the colors of the gradient, their position and number.

Parameters:

colorStops -- [out] A pointer to the memory location, where the array of the gradient's ColorStop is stored.

Returns:

The number of colors used in the gradient. This value corresponds to the length of the colorStops array.

FillSpread spread() const noexcept

Gets the FillSpread value of the fill.

Returns:

The FillSpread value of this Fill.

Matrix transform() const noexcept

Gets the matrix of the affine transformation of the gradient fill.

In case no transformation was applied, the identity matrix is returned.

Returns:

The augmented transformation matrix.

Fill *duplicate() const noexcept

Creates a copy of the Fill object.

Return a newly created Fill object with the properties copied from the original.

Returns:

A copied Fill object when succeed, nullptr otherwise.

uint32_t identifier() const noexcept

Return the unique id value of the Fill instance.

This method can be called for checking the current concrete instance type.

Returns:

The type id of the Fill instance.

Public Members

Impl *pImpl

Protected Functions

Fill(const Fill&) = delete
const Fill &operator=(const Fill&) = delete
Fill()
struct ColorStop
#include <thorvg.h>

A data structure storing the information about the color and its relative position inside the gradient bounds.

Public Members

float offset

The relative position of the color.

uint8_t r

The red color channel value in the range [0 ~ 255].

uint8_t g

The green color channel value in the range [0 ~ 255].

uint8_t b

The blue color channel value in the range [0 ~ 255].

uint8_t a

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

class Canvas
#include <thorvg.h>

An abstract class for drawing graphical elements.

A canvas is an entity responsible for drawing the target. It sets up the drawing engine and the buffer, which can be drawn on the screen. It also manages given Paint objects.

Note

A Canvas behavior depends on the raster engine though the final content of the buffer is expected to be identical.

Warning

The Paint objects belonging to one Canvas can't be shared among multiple Canvases.

Subclassed by tvg::GlCanvas, tvg::SwCanvas, tvg::WgCanvas

Public Functions

Canvas(RenderMethod*)
virtual ~Canvas()
Result reserve(uint32_t n) noexcept

Sets the size of the container, where all the paints pushed into the Canvas are stored.

If the number of objects pushed into the Canvas is known in advance, calling the function prevents multiple memory reallocation, thus improving the performance.

Parameters:

n -- [in] The number of objects for which the memory is to be reserved.

Returns:

Result::Success when succeed.

std::list<Paint*> &paints() noexcept

Returns the list of the paints that currently held by the Canvas.

This function provides the list of paint nodes, allowing users a direct opportunity to modify the scene tree.

See also

Canvas::sync()

Note

Experimental API

Warning

Please avoid accessing the paints during Canvas update/draw. You can access them after calling sync().

virtual Result push(std::unique_ptr<Paint> paint) noexcept

Passes drawing elements to the Canvas using Paint objects.

Only pushed paints in the canvas will be drawing targets. They are retained by the canvas until you call Canvas::clear().

See also

Canvas::paints()

See also

Canvas::clear()

Note

The rendering order of the paints is the same as the order as they were pushed into the canvas. Consider sorting the paints before pushing them if you intend to use layering.

Parameters:

paint -- [in] A Paint object to be drawn.

Return values:

  • Result::Success -- When succeed.

  • Result::MemoryCorruption -- In case a nullptr is passed as the argument.

  • Result::InsufficientCondition -- An internal error.

virtual Result clear(bool free = true) noexcept

Clear the internal canvas resources that used for the drawing.

This API sets the total number of paints pushed into the canvas to zero. Depending on the value of the free argument, the paints are either freed or retained. So if you need to update paint properties while maintaining the existing scene structure, you can set free = false.

See also

Canvas::push()

See also

Canvas::paints()

Parameters:

free -- [in] If true, the memory occupied by paints is deallocated, otherwise it is not.

Return values:

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

virtual Result update(Paint *paint = nullptr) noexcept

Request the canvas to update the paint objects.

If a nullptr is passed all paint objects retained by the Canvas are updated, otherwise only the paint to which the given paint points.

Note

The Update behavior can be asynchronous if the assigned thread number is greater than zero.

Parameters:

paint -- [in] A pointer to the Paint object or nullptr.

Return values:

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

virtual Result draw() noexcept

Requests the canvas to draw the Paint objects.

See also

Canvas::sync()

Note

Drawing can be asynchronous if the assigned thread number is greater than zero. To guarantee the drawing is done, call sync() afterwards.

Return values:

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

virtual Result viewport(int32_t x, int32_t y, int32_t w, int32_t h) noexcept

Sets the drawing region in the canvas.

This function defines the rectangular area of the canvas that will be used for drawing operations. The specified viewport is used to clip the rendering output to the boundaries of the rectangle.

See also

SwCanvas::target()

See also

GlCanvas::target()

See also

WgCanvas::target()

Note

When resetting the target, the viewport will also be reset to the target size.

Note

Experimental API

Warning

It's not allowed to change the viewport during Canvas::push() - Canvas::sync() or Canvas::update() - Canvas::sync().

Parameters:

  • x -- [in] The x-coordinate of the upper-left corner of the rectangle.

  • y -- [in] The y-coordinate of the upper-left corner of the rectangle.

  • w -- [in] The width of the rectangle.

  • h -- [in] The height of the rectangle.

Return values:

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

virtual Result sync() noexcept

Guarantees that drawing task is finished.

The Canvas rendering can be performed asynchronously. To make sure that rendering is finished, the sync() must be called after the draw() regardless of threading.

See also

Canvas::draw()

Return values:

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

Public Members

Impl *pImpl

Protected Functions

Canvas(const Canvas&) = delete
const Canvas &operator=(const Canvas&) = delete
Canvas()
class LinearGradient : public tvg::Fill
#include <thorvg.h>

A class representing the linear gradient fill of the Shape object.

Besides the APIs inherited from the Fill class, it enables setting and getting the linear gradient bounds. The behavior outside the gradient bounds depends on the value specified in the spread API.

Public Functions

~LinearGradient()
Result linear(float x1, float y1, float x2, float y2) noexcept

Sets the linear gradient bounds.

The bounds of the linear gradient are defined as a surface constrained by two parallel lines crossing the given points (x1, y1) and (x2, y2), respectively. Both lines are perpendicular to the line linking (x1, y1) and (x2, y2).

Note

In case the first and the second points are equal, an object filled with such a gradient fill is not rendered.

Parameters:

  • x1 -- [in] The horizontal coordinate of the first point used to determine the gradient bounds.

  • y1 -- [in] The vertical coordinate of the first point used to determine the gradient bounds.

  • x2 -- [in] The horizontal coordinate of the second point used to determine the gradient bounds.

  • y2 -- [in] The vertical coordinate of the second point used to determine the gradient bounds.

Return values:

Result::Success -- when succeed.

Result linear(float *x1, float *y1, float *x2, float *y2) const noexcept

Gets the linear gradient bounds.

The bounds of the linear gradient are defined as a surface constrained by two parallel lines crossing the given points (x1, y1) and (x2, y2), respectively. Both lines are perpendicular to the line linking (x1, y1) and (x2, y2).

Parameters:

  • x1 -- [out] The horizontal coordinate of the first point used to determine the gradient bounds.

  • y1 -- [out] The vertical coordinate of the first point used to determine the gradient bounds.

  • x2 -- [out] The horizontal coordinate of the second point used to determine the gradient bounds.

  • y2 -- [out] The vertical coordinate of the second point used to determine the gradient bounds.

Return values:

Result::Success -- when succeed.

Public Members

Impl *pImpl

Public Static Functions

static std::unique_ptr<LinearGradient> gen() noexcept

Creates a new LinearGradient object.

Returns:

A new LinearGradient object.

static uint32_t identifier() noexcept

Return the unique id value of this class.

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

Returns:

The type id of the LinearGradient class.

Protected Functions

LinearGradient(const LinearGradient&) = delete
const LinearGradient &operator=(const LinearGradient&) = delete
LinearGradient()
class RadialGradient : public tvg::Fill
#include <thorvg.h>

A class representing the radial gradient fill of the Shape object.

Public Functions

~RadialGradient()
Result radial(float cx, float cy, float radius) noexcept

Sets the radial gradient bounds.

The radial gradient bounds are defined as a circle centered in a given point (cx, cy) of a given radius.

Parameters:

  • cx -- [in] The horizontal coordinate of the center of the bounding circle.

  • cy -- [in] The vertical coordinate of the center of the bounding circle.

  • radius -- [in] The radius of the bounding circle.

Return values:

Result::Success -- when succeed, Result::InvalidArguments in case the radius value is zero or less.

Result radial(float *cx, float *cy, float *radius) const noexcept

Gets the radial gradient bounds.

The radial gradient bounds are defined as a circle centered in a given point (cx, cy) of a given radius.

Parameters:

  • cx -- [out] The horizontal coordinate of the center of the bounding circle.

  • cy -- [out] The vertical coordinate of the center of the bounding circle.

  • radius -- [out] The radius of the bounding circle.

Return values:

Result::Success -- when succeed.

Public Members

Impl *pImpl

Public Static Functions

static std::unique_ptr<RadialGradient> gen() noexcept

Creates a new RadialGradient object.

Returns:

A new RadialGradient object.

static uint32_t identifier() noexcept

Return the unique id value of this class.

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

Returns:

The type id of the RadialGradient class.

Protected Functions

RadialGradient(const RadialGradient&) = delete
const RadialGradient &operator=(const RadialGradient&) = delete
RadialGradient()
class Shape : public tvg::Paint
#include <thorvg.h>

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.

Public Functions

~Shape()
Result reset() noexcept

Resets the properties of the shape path.

The transformation matrix, the color, the fill and the stroke properties are retained.

Note

The memory, where the path data is stored, is not deallocated at this stage for caching effect.

Return values:

Result::Success -- when succeed.

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:

  • x -- [in] The horizontal coordinate of the initial point of the sub-path.

  • y -- [in] The vertical coordinate of the initial point of the sub-path.

Return values:

Result::Success -- when succeed.

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.

Note

In case this is the first command in the path, it corresponds to the moveTo() call.

Parameters:

  • x -- [in] The horizontal coordinate of the end-point of the line.

  • y -- [in] The vertical coordinate of the end-point of the line.

Return values:

Result::Success -- when succeed.

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.

Note

In case this is the first command in the path, no data from the path are rendered.

Parameters:

  • cx1 -- [in] The horizontal coordinate of the 1st control point.

  • cy1 -- [in] The vertical coordinate of the 1st control point.

  • cx2 -- [in] The horizontal coordinate of the 2nd control point.

  • cy2 -- [in] The vertical coordinate of the 2nd control point.

  • x -- [in] The horizontal coordinate of the end-point of the curve.

  • y -- [in] The vertical coordinate of the end-point of the curve.

Return values:

Result::Success -- when succeed.

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.

Note

In case the sub-path does not contain any points, this function has no effect.

Return values:

Result::Success -- when succeed.

Result appendRect(float x, float y, float w, float h, float rx = 0, float ry = 0) 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)

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.

Parameters:

  • x -- [in] The horizontal coordinate of the upper left corner of the rectangle.

  • y -- [in] The vertical coordinate of the upper left corner of the rectangle.

  • w -- [in] The width of the rectangle.

  • h -- [in] The height of the rectangle.

  • rx -- [in] The x-axis radius of the ellipse defining the rounded corners of the rectangle.

  • ry -- [in] The y-axis radius of the ellipse defining the rounded corners of the rectangle.

Return values:

Result::Success -- when succeed.

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:

  • cx -- [in] The horizontal coordinate of the center of the ellipse.

  • cy -- [in] The vertical coordinate of the center of the ellipse.

  • rx -- [in] The x-axis radius of the ellipse.

  • ry -- [in] The y-axis radius of the ellipse.

Return values:

Result::Success -- when succeed.

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.

Note

Setting sweep value greater than 360 degrees, is equivalent to calling appendCircle(cx, cy, radius, radius).

Parameters:

  • cx -- [in] The horizontal coordinate of the center of the arc.

  • cy -- [in] The vertical coordinate of the center of the arc.

  • radius -- [in] The radius of the arc.

  • startAngle -- [in] The start angle of the arc given in degrees, measured counter-clockwise from the horizontal line.

  • sweep -- [in] The central angle of the arc given in degrees, measured counter-clockwise from startAngle.

  • pie -- [in] Specifies whether to draw radii from the arc's center to both of its end-point - drawn if true.

Return values:

Result::Success -- when succeed.

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. If the number of points in the pts array is different than the number required by the cmds array, the shape with this sub-path will not be displayed on the screen.

Note

The interface is designed for optimal path setting if the caller has a completed path commands already.

Parameters:

  • cmds -- [in] The array of the commands in the sub-path.

  • cmdCnt -- [in] The number of the sub-path's commands.

  • pts -- [in] The array of the two-dimensional points.

  • ptsCnt -- [in] The number of the points in the pts array.

Return values:

Result::Success -- when succeed, Result::InvalidArguments otherwise.

Result stroke(float width) noexcept

Sets the stroke width for all of the figures from the path.

Parameters:

width -- [in] The width of the stroke. The default value is 0.

Return values:

Result::Success -- when succeed, Result::FailedAllocation otherwise.

Result stroke(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255) noexcept

Sets the color of the stroke for all of the figures from the path.

Parameters:

  • r -- [in] The red color channel value in the range [0 ~ 255]. The default value is 0.

  • g -- [in] The green color channel value in the range [0 ~ 255]. The default value is 0.

  • b -- [in] The blue color channel value in the range [0 ~ 255]. The default value is 0.

  • a -- [in] The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.

Return values:

Result::Success -- when succeed, Result::FailedAllocation otherwise.

Result stroke(std::unique_ptr<Fill> f) noexcept

Sets the gradient fill of the stroke for all of the figures from the path.

Parameters:

f -- [in] 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.

Result stroke(const float *dashPattern, uint32_t cnt) noexcept

Sets the dash pattern of the stroke.

Note

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.

Parameters:

  • dashPattern -- [in] The array of consecutive pair values of the dash length and the gap length.

  • cnt -- [in] 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 dashPattern is nullptr and cnt > 0, cnt is zero, any of the dash pattern values is zero or less.

Result stroke(StrokeCap cap) noexcept

Sets the cap style of the stroke in the open sub-paths.

Parameters:

cap -- [in] The cap style value. The default value is StrokeCap::Square.

Return values:

Result::Success -- when succeed, Result::FailedAllocation otherwise.

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:

join -- [in] The join style value. The default value is StrokeJoin::Bevel.

Return values:

Result::Success -- when succeed, Result::FailedAllocation otherwise.

Result strokeMiterlimit(float miterlimit) noexcept

Sets the stroke miterlimit.

Since

0.11

Parameters:

miterlimit -- [in] The miterlimit imposes a limit on the extent of the stroke join, when the StrokeJoin::Miter join style is set. The default value is 4.

Return values:

Result::Success -- when succeed, Result::NonSupport unsupported value, Result::FailedAllocation otherwise.

Result fill(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255) noexcept

Sets the solid color for all of the figures from the path.

The parts of the shape defined as inner are colored.

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Note

ClipPath won't use the fill values. (see: enum class CompositeMethod::ClipPath)

Parameters:

  • r -- [in] The red color channel value in the range [0 ~ 255]. The default value is 0.

  • g -- [in] The green color channel value in the range [0 ~ 255]. The default value is 0.

  • b -- [in] The blue color channel value in the range [0 ~ 255]. The default value is 0.

  • a -- [in] The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.

Return values:

Result::Success -- when succeed.

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.

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Parameters:

f -- [in] The unique pointer to the gradient fill.

Return values:

Result::Success -- when succeed, Result::MemoryCorruption otherwise.

Result fill(FillRule r) noexcept

Sets the fill rule for the Shape object.

Parameters:

r -- [in] The fill rule value. The default value is FillRule::Winding.

Return values:

Result::Success -- when succeed.

Result order(bool strokeFirst) noexcept

Sets the rendering order of the stroke and the fill.

Since

0.10

Parameters:

strokeFirst -- [in] If true the stroke is rendered before the fill, otherwise the stroke is rendered as the second one (the default option).

Return values:

Result::Success -- when succeed, Result::FailedAllocation otherwise.

uint32_t pathCommands(const PathCommand **cmds) const noexcept

Gets the commands data of the path.

Parameters:

cmds -- [out] The pointer to the array of the commands from the path.

Returns:

The length of the cmds array when succeed, zero otherwise.

uint32_t pathCoords(const Point **pts) const noexcept

Gets the points values of the path.

Parameters:

pts -- [out] The pointer to the array of the two-dimensional points from the path.

Returns:

The length of the pts array when succeed, zero otherwise.

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.

Result fillColor(uint8_t *r, uint8_t *g, uint8_t *b, uint8_t *a = nullptr) const noexcept

Gets the solid color of the shape.

Parameters:

  • r -- [out] The red color channel value in the range [0 ~ 255].

  • g -- [out] The green color channel value in the range [0 ~ 255].

  • b -- [out] The blue color channel value in the range [0 ~ 255].

  • a -- [out] 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() const noexcept

Gets the fill rule value.

Returns:

The fill rule value of the shape.

float strokeWidth() const noexcept

Gets the stroke width.

Returns:

The stroke width value when succeed, zero if no stroke was set.

Result strokeColor(uint8_t *r, uint8_t *g, uint8_t *b, uint8_t *a = nullptr) const noexcept

Gets the color of the shape's stroke.

Parameters:

  • r -- [out] The red color channel value in the range [0 ~ 255].

  • g -- [out] The green color channel value in the range [0 ~ 255].

  • b -- [out] The blue color channel value in the range [0 ~ 255].

  • a -- [out] The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Return values:

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

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.

uint32_t strokeDash(const float **dashPattern) const noexcept

Gets the dash pattern of the stroke.

Parameters:

dashPattern -- [out] The pointer to the memory, where the dash pattern array is stored.

Returns:

The length of the dashPattern array.

StrokeCap strokeCap() const noexcept

Gets the cap style used for stroking the path.

Returns:

The cap style value of the stroke.

StrokeJoin strokeJoin() const noexcept

Gets the join style value used for stroking the path.

Returns:

The join style value of the stroke.

float strokeMiterlimit() const noexcept

Gets the stroke miterlimit.

Since

0.11

Returns:

The stroke miterlimit value when succeed, 4 if no stroke was set.

Public Members

Impl *pImpl

Public Static Functions

static std::unique_ptr<Shape> gen() noexcept

Creates a new Shape object.

Returns:

A new Shape object.

static uint32_t identifier() noexcept

Return the unique id value of this class.

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

Returns:

The type id of the Shape class.

Protected Functions

Shape(const Shape&) = delete
const Shape &operator=(const Shape&) = delete
Shape()
class Picture : public tvg::Paint
#include <thorvg.h>

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.

Note

See Animation class if the picture data is animatable.

Public Functions

~Picture()
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.

See also

Initializer::init()

Note

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

Parameters:

path -- [in] 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.

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

Deprecated:

Use load(const char* data, uint32_t size, const std::string& mimeType, bool copy) instead.

See also

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

Warning

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

Parameters:

  • data -- [in] A pointer to a memory location where the content of the picture file is stored.

  • size -- [in] The size in bytes of the memory occupied by the data.

  • copy -- [in] 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.

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.

Since

0.5

Note

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

Warning

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

Parameters:

  • data -- [in] A pointer to a memory location where the content of the picture file is stored.

  • size -- [in] The size in bytes of the memory occupied by the data.

  • mimeType -- [in] 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.

  • copy -- [in] 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.

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:

  • w -- [in] A new width of the image in pixels.

  • h -- [in] A new height of the image in pixels.

Return values:

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

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

Gets the size of the image.

Parameters:

  • w -- [out] The width of the image in pixels.

  • h -- [out] The height of the image in pixels.

Return values:

Result::Success -- when succeed.

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.

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.

Since

0.9

Parameters:

  • paint -- [in] A Tvg_Paint pointer to the picture object.

  • data -- [in] A pointer to a memory location where the content of the picture raw data is stored.

  • w -- [in] The width of the image data in pixels.

  • h -- [in] The height of the image data in pixels.

  • premultiplied -- [in] If true, the given image data is alpha-premultiplied.

  • copy -- [in] If true the data are copied into the engine local buffer, otherwise they are not.

Return values:

  • Result::Success -- When succeed, Result::InsufficientCondition otherwise.

  • Result::FailedAllocation -- An internal error possibly with memory allocation.

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.

Note

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

Note

Experimental API

Warning

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

Parameters:

  • triangles -- [in] An array of Polygons(triangles) that make up the mesh, or null to remove the mesh.

  • triangleCnt -- [in] The number of Polygons(triangles) provided, or 0 to remove the mesh.

Return values:

  • Result::Success -- When succeed.

  • Result::Unknown -- If fails

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.

Note

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

Note

Experimental API

Warning

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

Parameters:

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

Returns:

The number of polygons in the array.

Public Members

friend Animation
Impl *pImpl

Public Static Functions

static std::unique_ptr<Picture> gen() noexcept

Creates a new Picture object.

Returns:

A new Picture object.

static uint32_t identifier() noexcept

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.

Protected Functions

Picture(const Picture&) = delete
const Picture &operator=(const Picture&) = delete
Picture()
class Scene : public tvg::Paint
#include <thorvg.h>

A class to composite children paints.

As the traditional graphics rendering method, TVG also enables scene-graph mechanism. This feature supports an array function for managing the multiple paints as one group paint.

As a group, the scene can be transformed, made translucent and composited with other target paints, its children will be affected by the scene world.

Public Functions

~Scene()
Result push(std::unique_ptr<Paint> paint) noexcept

Passes drawing elements to the Scene using Paint objects.

Only the paints pushed into the scene will be the drawn targets. The paints are retained by the scene until Scene::clear() is called.

See also

Scene::paints()

See also

Scene::clear()

Note

The rendering order of the paints is the same as the order as they were pushed. Consider sorting the paints before pushing them if you intend to use layering.

Parameters:

paint -- [in] A Paint object to be drawn.

Return values:

Result::Success -- when succeed, Result::MemoryCorruption otherwise.

Result reserve(uint32_t size) noexcept

Sets the size of the container, where all the paints pushed into the Scene are stored.

If the number of objects pushed into the scene is known in advance, calling the function prevents multiple memory reallocation, thus improving the performance.

Parameters:

size -- [in] The number of objects for which the memory is to be reserved.

Returns:

Result::Success when succeed, Result::FailedAllocation otherwise.

std::list<Paint*> &paints() noexcept

Returns the list of the paints that currently held by the Scene.

This function provides the list of paint nodes, allowing users a direct opportunity to modify the scene tree.

See also

Canvas::sync()

See also

Scene::push()

See also

Scene::clear()

Note

Experimental API

Warning

Please avoid accessing the paints during Scene update/draw. You can access them after calling Canvas::sync().

Result clear(bool free = true) noexcept

Sets the total number of the paints pushed into the scene to be zero. Depending on the value of the free argument, the paints are freed or not.

Since

0.2

Warning

If you don't free the paints they become dangled. They are supposed to be reused, otherwise you are responsible for their lives. Thus please use the free argument only when you know how it works, otherwise it's not recommended.

Parameters:

free -- [in] If true, the memory occupied by paints is deallocated, otherwise it is not.

Return values:

Result::Success -- when succeed

Public Members

Impl *pImpl

Public Static Functions

static std::unique_ptr<Scene> gen() noexcept

Creates a new Scene object.

Returns:

A new Scene object.

static uint32_t identifier() noexcept

Return the unique id value of this class.

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

Returns:

The type id of the Scene class.

Protected Functions

Scene(const Scene&) = delete
const Scene &operator=(const Scene&) = delete
Scene()
class Text : public tvg::Paint
#include <thorvg.h>

A class to represent text objects in a graphical context, allowing for rendering and manipulation of unicode text.

Note

Experimental API

Public Functions

~Text()
Result font(const char *name, float size, const char *style = nullptr) noexcept

Sets the font properties for the text.

This function allows you to define the font characteristics used for text rendering. It sets the font name, size and optionally the style.

Note

Experimental API

Parameters:

  • name -- [in] The name of the font. This should correspond to a font available in the canvas.

  • size -- [in] The size of the font in points. This determines how large the text will appear.

  • style -- [in] The style of the font. It can be used to set the font to 'italic'. If not specified, the default style is used. Only 'italic' style is supported currently.

Return values:

  • Result::Success -- when the font properties are set successfully.

  • Result::InsufficientCondition -- when the specified name cannot be found.

Result text(const char *text) noexcept

Assigns the given unicode text to be rendered.

This function sets the unicode string that will be displayed by the rendering system. The text is set according to the specified UTF encoding method, which defaults to UTF-8.

Note

Experimental API

Parameters:

text -- [in] The multi-byte text encoded with utf8 string to be rendered.

Return values:

Result::Success -- when succeed.

Result fill(uint8_t r, uint8_t g, uint8_t b) noexcept

Sets the text color.

See also

Text::font()

Note

Experimental API

Parameters:

  • r -- [in] The red color channel value in the range [0 ~ 255]. The default value is 0.

  • g -- [in] The green color channel value in the range [0 ~ 255]. The default value is 0.

  • b -- [in] The blue color channel value in the range [0 ~ 255]. The default value is 0.

Return values:

  • Result::Success -- when succeed.

  • Result::InsufficientCondition -- when the font has not been set up prior to this operation.

Result fill(std::unique_ptr<Fill> f) noexcept

Sets the gradient fill for all of the figures from the text.

The parts of the text defined as inner are filled.

See also

Text::font()

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

Note

Experimental API

Parameters:

f -- [in] The unique pointer to the gradient fill.

Return values:

  • Result::Success -- when succeed, Result::MemoryCorruption otherwise.

  • Result::InsufficientCondition -- when the font has not been set up prior to this operation.

Public Members

Impl *pImpl

Public Static Functions

static Result load(const std::string &path) noexcept

Loads a scalable font data(ttf) 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 font data.

See also

Text::unload(const std::string& path)

Note

Experimental API

Parameters:

path -- [in] The path to the font 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.

static Result unload(const std::string &path) noexcept

Unloads the specified scalable font data (TTF) that was previously loaded.

This function is used to release resources associated with a font file that has been loaded into memory.

See also

Text::load(const std::string& path)

Note

If the font data is currently in use, it will not be immediately unloaded.

Note

Experimental API

Parameters:

path -- [in] The file path of the loaded font.

Return values:

  • Result::Success -- Successfully unloads the font data.

  • Result::InsufficientCondition -- Fails if the loader is not initialized.

static std::unique_ptr<Text> gen() noexcept

Creates a new Text object.

Note

Experimental API

Returns:

A new Text object.

static uint32_t identifier() noexcept

Return the unique id value of this class.

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

Returns:

The type id of the Text class.

Protected Functions

Text(const Text&) = delete
const Text &operator=(const Text&) = delete
Text()
class SwCanvas : public tvg::Canvas
#include <thorvg.h>

A class for the rendering graphical elements with a software raster engine.

Public Types

enum Colorspace

Enumeration specifying the methods of combining the 8-bit color channels into 32-bit color.

Values:

enumerator ABGR8888

The channels are joined in the order: alpha, blue, green, red. Colors are alpha-premultiplied. (a << 24 | b << 16 | g << 8 | r)

enumerator ARGB8888

The channels are joined in the order: alpha, red, green, blue. Colors are alpha-premultiplied. (a << 24 | r << 16 | g << 8 | b)

enumerator ABGR8888S

The channels are joined in the order: alpha, blue, green, red. Colors are un-alpha-premultiplied.

Since

0.12

enumerator ARGB8888S

The channels are joined in the order: alpha, red, green, blue. Colors are un-alpha-premultiplied.

Since

0.12

enum MempoolPolicy

Enumeration specifying the methods of Memory Pool behavior policy.

Since

0.4

Values:

enumerator Default

Default behavior that ThorVG is designed to.

enumerator Shareable

Memory Pool is shared among the SwCanvases.

enumerator Individual

Allocate designated memory pool that is only used by current instance.

Public Functions

~SwCanvas()
Result target(uint32_t *buffer, uint32_t stride, uint32_t w, uint32_t h, Colorspace cs) noexcept

Sets the drawing target for the rasterization.

The buffer of a desirable size should be allocated and owned by the caller.

See also

Canvas::viewport()

Warning

Do not access buffer during Canvas::push() - Canvas::sync(). It should not be accessed while the engine is writing on it.

Parameters:

  • buffer -- [in] A pointer to a memory block of the size stride x h, where the raster data are stored.

  • stride -- [in] The stride of the raster image - greater than or equal to w.

  • w -- [in] The width of the raster image.

  • h -- [in] The height of the raster image.

  • cs -- [in] The value specifying the way the 32-bits colors should be read/written.

Return values:

  • Result::Success -- When succeed.

  • Result::MemoryCorruption -- When casting in the internal function implementation failed.

  • Result::InvalidArguments -- In case no valid pointer is provided or the width, or the height or the stride is zero.

  • Result::NonSupport -- In case the software engine is not supported.

Result mempool(MempoolPolicy policy) noexcept

Set sw engine memory pool behavior policy.

Basically ThorVG draws a lot of shapes, it allocates/deallocates a few chunk of memory while processing rendering. It internally uses one shared memory pool which can be reused among the canvases in order to avoid memory overhead.

Thus ThorVG suggests using a memory pool policy to satisfy user demands, if it needs to guarantee the thread-safety of the internal data access.

Since

0.4

Note

When policy is set as MempoolPolicy::Individual, the current instance of canvas uses its own individual memory data, which is not shared with others. This is necessary when the canvas is accessed on a worker-thread.

Warning

It's not allowed after pushing any paints.

Parameters:

policy -- [in] The method specifying the Memory Pool behavior. The default value is MempoolPolicy::Default.

Return values:

  • Result::Success -- When succeed.

  • Result::InsufficientCondition -- If the canvas contains some paints already.

  • Result::NonSupport -- In case the software engine is not supported.

Public Members

Impl *pImpl

Public Static Functions

static std::unique_ptr<SwCanvas> gen() noexcept

Creates a new SwCanvas object.

Returns:

A new SwCanvas object.

Protected Functions

SwCanvas(const SwCanvas&) = delete
const SwCanvas &operator=(const SwCanvas&) = delete
SwCanvas()
class GlCanvas : public tvg::Canvas
#include <thorvg.h>

A class for the rendering graphic elements with a GL raster engine.

Note

Experimental API

Warning

Please do not use it. This class is not fully supported yet.

Public Functions

~GlCanvas()
Result target(int32_t id, uint32_t w, uint32_t h) noexcept

Sets the drawing target for rasterization.

This function specifies the drawing target where the rasterization will occur. It can target a specific framebuffer object (FBO) or the main surface.

See also

Canvas::viewport()

Note

Currently, this only allows the GL_RGBA8 color space format.

Note

Experimental API

Warning

This API is experimental and not officially supported. It may be modified or removed in future versions.

Warning

Drawing on the main surface is currently not permitted. If the identifier (id) is set to 0, the operation will be aborted.

Parameters:

  • id -- [in] The GL target ID, usually indicating the FBO ID. A value of 0 specifies the main surface.

  • w -- [in] The width (in pixels) of the raster image.

  • h -- [in] The height (in pixels) of the raster image.

Public Members

Impl *pImpl

Public Static Functions

static std::unique_ptr<GlCanvas> gen() noexcept

Creates a new GlCanvas object.

Note

Experimental API

Returns:

A new GlCanvas object.

Protected Functions

GlCanvas(const GlCanvas&) = delete
const GlCanvas &operator=(const GlCanvas&) = delete
GlCanvas()
class WgCanvas : public tvg::Canvas
#include <thorvg.h>

A class for the rendering graphic elements with a WebGPU raster engine.

Note

Experimental API

Warning

Please do not use it. This class is not fully supported yet.

Public Functions

~WgCanvas()
Result target(void *window, uint32_t w, uint32_t h) noexcept

Sets the target window for the rasterization.

See also

Canvas::viewport()

Note

Experimental API

Warning

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

Public Members

Impl *pImpl

Public Static Functions

static std::unique_ptr<WgCanvas> gen() noexcept

Creates a new WgCanvas object.

Note

Experimental API

Returns:

A new WgCanvas object.

Protected Functions

WgCanvas(const WgCanvas&) = delete
const WgCanvas &operator=(const WgCanvas&) = delete
WgCanvas()
class Initializer
#include <thorvg.h>

A class that enables initialization and termination of the TVG engines.

Public Functions

Initializer() = delete
~ Initializer ()=delete

Public Static Functions

static Result init(CanvasEngine engine, uint32_t threads) noexcept

Initializes TVG engines.

TVG requires the running-engine environment. TVG runs its own task-scheduler for parallelizing rendering tasks efficiently. You can indicate the number of threads, the count of which is designated threads. In the initialization step, TVG will generate/spawn the threads as set by threads count.

See also

Initializer::term()

Note

The Initializer keeps track of the number of times it was called. Threads count is fixed at the first init() call.

Parameters:

  • engine -- [in] The engine types to initialize. This is relative to the Canvas types, in which it will be used. For multiple backends bitwise operation is allowed.

  • threads -- [in] The number of additional threads. Zero indicates only the main thread is to be used.

Return values:

  • Result::Success -- When succeed.

  • Result::FailedAllocation -- An internal error possibly with memory allocation.

  • Result::InvalidArguments -- If unknown engine type chosen.

  • Result::NonSupport -- In case the engine type is not supported on the system.

  • Result::Unknown -- Others.

static Result term(CanvasEngine engine) noexcept

Terminates TVG engines.

See also

Initializer::init()

Note

Initializer does own reference counting for multiple calls.

Parameters:

engine -- [in] The engine types to terminate. This is relative to the Canvas types, in which it will be used. For multiple backends bitwise operation is allowed

Return values:

  • Result::Success -- When succeed.

  • Result::InsufficientCondition -- In case there is nothing to be terminated.

  • Result::InvalidArguments -- If unknown engine type chosen.

  • Result::NonSupport -- In case the engine type is not supported on the system.

  • Result::Unknown -- Others.

class Animation
#include <thorvg.h>

The Animation class enables manipulation of animatable images.

This class supports the display and control of animation frames.

Since

0.13

Subclassed by tvg::LottieAnimation

Public Functions

~Animation()
Result frame(float no) noexcept

Specifies the current frame in the animation.

See also

totalFrame()

Note

For efficiency, ThorVG ignores updates to the new frame value if the difference from the current frame value is less than 0.001. In such cases, it returns Result::InsufficientCondition. Values less than 0.001 may be disregarded and may not be accurately retained by the Animation.

Parameters:

no -- [in] The index of the animation frame to be displayed. The index should be less than the totalFrame().

Return values:

  • Result::Success -- Successfully set the frame.

  • Result::InsufficientCondition -- if the given no is the same as the current frame value.

  • Result::NonSupport -- The current Picture data does not support animations.

Picture *picture() const noexcept

Retrieves a picture instance associated with this animation instance.

This function provides access to the picture instance that can be used to load animation formats, such as Lottie(json). After setting up the picture, it can be pushed to the designated canvas, enabling control over animation frames with this Animation instance.

Warning

The picture instance is owned by Animation. It should not be deleted manually.

Returns:

A picture instance that is tied to this animation.

float curFrame() const noexcept

Retrieves the current frame number of the animation.

See also

Animation::frame(float no)

See also

Animation::totalFrame()

Note

If the Picture is not properly configured, this function will return 0.

Returns:

The current frame number of the animation, between 0 and totalFrame() - 1.

float totalFrame() const noexcept

Retrieves the total number of frames in the animation.

Note

Frame numbering starts from 0.

Note

If the Picture is not properly configured, this function will return 0.

Returns:

The total number of frames in the animation.

float duration() const noexcept

Retrieves the duration of the animation in seconds.

Note

If the Picture is not properly configured, this function will return 0.

Returns:

The duration of the animation in seconds.

Result segment(float begin, float end) noexcept

Specifies the playback segment of the animation.

The set segment is designated as the play area of the animation. This is useful for playing a specific segment within the entire animation. After setting, the number of animation frames and the playback time are calculated by mapping the playback segment as the entire range.

See also

LottieAnimation::segment(const char* marker)

Note

Range from 0.0~1.0

Note

If a marker has been specified, its range will be disregarded.

Note

Experimental API

Parameters:

  • begin -- [in] segment start.

  • end -- [in] segment end.

Return values:

  • Result::Success -- When succeed.

  • Result::InsufficientCondition -- In case the animation is not loaded.

  • Result::InvalidArguments -- When the given parameter is invalid.

  • Result::NonSupport -- When it's not animatable.

Result segment(float *begin, float *end = nullptr) noexcept

Gets the current segment.

Note

Experimental API

Parameters:

  • begin -- [out] segment start.

  • end -- [out] segment end.

Return values:

  • Result::Success -- When succeed.

  • Result::InsufficientCondition -- In case the animation is not loaded.

  • Result::InvalidArguments -- When the given parameter is invalid.

  • Result::NonSupport -- When it's not animatable.

Public Members

Impl *pImpl

Public Static Functions

static std::unique_ptr<Animation> gen() noexcept

Creates a new Animation object.

Returns:

A new Animation object.

Protected Functions

Animation(const Animation&) = delete
const Animation &operator=(const Animation&) = delete
Animation()
class Saver
#include <thorvg.h>

A class for exporting a paint object into a specified file, from which to recover the paint data later.

ThorVG provides a feature for exporting & importing paint data. The Saver role is to export the paint data to a file. It's useful when you need to save the composed scene or image from a paint object and recreate it later.

The file format is decided by the extension name(i.e. "*.tvg") while the supported formats depend on the TVG packaging environment. If it doesn't support the file format, the save() method returns the Result::NonSupport result.

Once you export a paint to the file successfully, you can recreate it using the Picture class.

See also

Picture::load()

Since

0.5

Public Functions

~Saver()
Result background(std::unique_ptr<Paint> paint) noexcept

Sets the base background content for the saved image.

Note

Experimental API

Parameters:

paint -- [in] The paint to be drawn as the background image for the saving paint.

Result save(std::unique_ptr<Paint> paint, const std::string &path, bool compress = true) noexcept

Exports the given paint data to the given path.

If the saver module supports any compression mechanism, it will optimize the data size. This might affect the encoding/decoding time in some cases. You can turn off the compression if you wish to optimize for speed.

See also

Saver::sync()

Since

0.5

Note

Saving can be asynchronous if the assigned thread number is greater than zero. To guarantee the saving is done, call sync() afterwards.

Parameters:

  • paint -- [in] The paint to be saved with all its associated properties.

  • path -- [in] A path to the file, in which the paint data is to be saved.

  • compress -- [in] If true then compress data if possible.

Return values:

  • Result::Success -- When succeed.

  • Result::InsufficientCondition -- If currently saving other resources.

  • Result::NonSupport -- When trying to save a file with an unknown extension or in an unsupported format.

  • Result::MemoryCorruption -- An internal error.

  • Result::Unknown -- In case an empty paint is to be saved.

Result save(std::unique_ptr<Animation> animation, const std::string &path, uint32_t quality = 100, uint32_t fps = 0) noexcept

Export the provided animation data to the specified file path.

This function exports the given animation data to the provided file path. You can also specify the desired frame rate in frames per second (FPS) by providing the fps parameter.

See also

Saver::sync()

Note

A higher frames per second (FPS) would result in a larger file size. It is recommended to use the default value.

Note

Saving can be asynchronous if the assigned thread number is greater than zero. To guarantee the saving is done, call sync() afterwards.

Note

Experimental API

Parameters:

  • animation -- [in] The animation to be saved, including all associated properties.

  • path -- [in] The path to the file where the animation will be saved.

  • quality -- [in] The encoded quality level. 0 is the minimum, 100 is the maximum value(recommended).

  • fps -- [in] The desired frames per second (FPS). For example, to encode data at 60 FPS, pass 60. Pass 0 to keep the original frame data.

Return values:

  • Result::Success -- if the export succeeds.

  • Result::InsufficientCondition -- if there are ongoing resource-saving operations.

  • Result::NonSupport -- if an attempt is made to save the file with an unknown extension or in an unsupported format.

  • Result::MemoryCorruption -- in case of an internal error.

  • Result::Unknown -- if attempting to save an empty paint.

Result sync() noexcept

Guarantees that the saving task is finished.

The behavior of the Saver works on a sync/async basis, depending on the threading setting of the Initializer. Thus, if you wish to have a benefit of it, you must call sync() after the save() in the proper delayed time. Otherwise, you can call sync() immediately.

See also

Saver::save()

Since

0.5

Note

The asynchronous tasking is dependent on the Saver module implementation.

Return values:

  • Result::Success -- when succeed.

  • Result::InsufficientCondition -- otherwise.

Public Members

Impl *pImpl

Public Static Functions

static std::unique_ptr<Saver> gen() noexcept

Creates a new Saver object.

Since

0.5

Returns:

A new Saver object.

Protected Functions

Saver(const Saver&) = delete
const Saver &operator=(const Saver&) = delete
Saver()
class Accessor
#include <thorvg.h>

The Accessor is a utility class to debug the Scene structure by traversing the scene-tree.

The Accessor helps you search specific nodes to read the property information, figure out the structure of the scene tree and its size.

Since

0.10

Warning

We strongly warn you not to change the paints of a scene unless you really know the design-structure.

Public Functions

~Accessor()
std::unique_ptr<Picture> set(std::unique_ptr<Picture> picture, std::function<bool(const Paint *paint)> func) noexcept

Set the access function for traversing the Picture scene tree nodes.

Note

The bitmap based picture might not have the scene-tree.

Parameters:

  • picture -- [in] The picture node to traverse the internal scene-tree.

  • func -- [in] The callback function calling for every paint nodes of the Picture.

Returns:

Return the given picture instance.

Public Members

Impl *pImpl

Public Static Functions

static std::unique_ptr<Accessor> gen() noexcept

Creates a new Accessor object.

Returns:

A new Accessor object.

Protected Functions

Accessor(const Accessor&) = delete
const Accessor &operator=(const Accessor&) = delete
Accessor()