Crate thorvg

Expand description

Safe, idiomatic Rust bindings to the ThorVG vector graphics library.

ThorVG is a production-ready vector graphics engine supporting SVG, Lottie animations, shapes, text, gradients, effects, and more.

These bindings wrap the ThorVG C API; consult it for the authoritative engine semantics. The bindings themselves are a work in progress: not every ThorVG API is wrapped yet, and the surface here may change between releases.

§`no_std` Support

This crate is no_std compatible (requires alloc). The std feature (enabled by default) adds file I/O APIs that accept std::path::Path (e.g., Picture::load, Thorvg::load_font).

To use in no_std, disable default features:

[dependencies]
thorvg = { version = "0.4", default-features = false }

no_std panic policy: the crate executes user-supplied closures (asset resolvers, accessor visitors) from inside extern "C" trampolines invoked by the C++ engine. In std builds the trampolines wrap each closure call in std::panic::catch_unwind and convert panics to a “failure” return; in no_std builds there is no catch_unwind.

This is sound regardless: a panic in your closure reaches the mandatory #[panic_handler], which diverges (-> !) and so cannot unwind back across the trampoline into the C++ frame. As a second backstop, the extern "C" trampolines are nounwind (Rust ≥ 1.81), so any forced unwind out of them aborts rather than invoking UB. Building with panic = "abort" is nonetheless recommended for no_std: it makes a panic terminate deterministically instead of depending on #[panic_handler] behaviour, and bare-metal targets usually require it to link anyway (no eh_personality).

§Cargo Features

Each feature is forwarded to thorvg-sys, controlling which ThorVG loaders and capabilities are compiled into the static library. All listed features are enabled by default.

Feature	Default	Effect
`vendored`	yes	Builds the bundled `ThorVG` source instead of linking a system one.
`std`	yes	Enables `std` and the `Path`-based file APIs (implies `file-io`).
`file-io`	yes	Enables `ThorVG`’s file-based loaders and savers.
`threads`	yes	Multi-threaded rendering; changes `Thorvg::init` to take a thread count.
`svg`	yes	SVG loader.
`lottie`	yes	Lottie animation loader.
`png`	yes	PNG image loader.
`fonts`	yes	Scalable font (TTF) support for text.
`expressions`	yes	Lottie expression evaluation.

§Quick Start

use thorvg::{Thorvg, ColorSpace};

// Initialize the engine — all objects borrow from this guard.
// With the `threads` feature (default): `Thorvg::init(threads: u32)`.
// Without it (bare-metal builds): `Thorvg::init()` — single-threaded only.
let engine = Thorvg::init(0).expect("Failed to initialize ThorVG");

// Create a canvas with a buffer
let mut canvas = engine.sw_canvas(Default::default()).expect("Failed to create canvas");
let mut buffer = vec![0u32; 800 * 600];
// Safety: buffer outlives the canvas.
unsafe {
    canvas
        .set_target(&mut buffer, 800, 800, 600, ColorSpace::ABGR8888)
        .expect("Failed to set target");
}

// Draw a red rectangle
let mut shape = engine.shape().unwrap();
shape.append_rect(thorvg::Rect::new(0.0, 0.0, 200.0, 200.0)).unwrap();
shape.set_fill_color(thorvg::Rgba::new(255, 0, 0, 255)).unwrap();
canvas.add(shape).unwrap();

// Render
canvas.draw(true).unwrap();
canvas.sync().unwrap();

Structs§

Accessor: Scene-tree traversal helper.
Animation: Controller for animatable content such as Lottie.
AudioInfo: Borrowed view of a Lottie audio layer’s current playback state.
BorrowedAccessor: Read-only view of an Accessor passed into for_each’s closure.
BorrowedLinearGradient: Read-only view of a linear gradient owned by a Shape.
BorrowedPaint: A read-only borrow of a paint owned by another object.
BorrowedRadialGradient: Read-only view of a radial gradient owned by a Shape.
Circle: An ellipse (or circle, when rx == ry).
ColorStop: A color stop in a gradient.
DropShadow: Parameters for Scene::add_drop_shadow_effect.
GaussianBlur: Parameters for Scene::add_gaussian_blur_effect.
GlCanvas: An OpenGL/ES-rendered canvas.
GlTarget: Parameters for GlCanvas::set_target.
GlyphMetrics: Layout metrics of a single glyph.
LinearGradient: A linear gradient fill.
LottieAnimation: Lottie animation controller with Lottie-specific extensions.
Marker: A named segment within a Lottie animation.
Matrix: A 3×3 affine transformation matrix.
Path: Vector path data — a sequence of commands paired with the points they consume.
Picture: A picture object for loading and displaying images (SVG, PNG, JPG, Lottie, etc.).
Point: A point in 2D space.
RadialGradient: A radial gradient fill.
Rect: An axis-aligned rectangle, optionally rounded.
Rgb: An 8-bit-per-channel RGB color.
Rgba: An 8-bit-per-channel RGB color with an alpha channel.
Saver: Exports paint objects or animations to files.
Scene: A scene that groups multiple paint objects.
Segments: Iterator over typed Segments produced by Path::segments.
Shape: A two-dimensional shape with path, fill, and stroke properties.
SwCanvas: A software-rendered canvas.
Text: A paint object for rendering Unicode text.
TextMetrics: Vertical font metrics for a Text object.
Thorvg: RAII guard owning the ThorVG engine lifetime.
Tint: Parameters for Scene::add_tint_effect.
Tritone: Parameters for Scene::add_tritone_effect.
WgCanvas: A WebGPU-rendered canvas.
WgContext: A caller-owned WebGPU context for WgCanvas::set_target_with_context.
WgContextTarget: Parameters for WgCanvas::set_target_with_context.
WgTarget: Parameters for WgCanvas::set_target.

Enums§

BlendMethod: Blending method for compositing paint objects.
BlurBorder: Edge-sampling behavior for Scene::add_gaussian_blur_effect.
BlurDirection: Axis along which a Scene::add_gaussian_blur_effect blur is applied.
BorrowedGradient: Discriminated read-only view of a gradient owned by a Shape.
ColorSpace: Pixel layout of a rendering buffer.
EngineOption: Engine rendering option, selected per canvas at creation.
Error: Errors returned by ThorVG operations.
FillRule: Fill rule for determining the interior of a shape.
FillSpread: How to fill the area outside the gradient bounds.
FilterMethod: Image filtering method used during scaling or transformation.
MaskMethod: Masking method for combining two paint objects.
MimeType: Picture data format passed to Picture::load_data.
PaintOrder: Rendering order of a shape’s fill and stroke.
PaintType: The concrete type of a paint object.
PathCommand: One of thorvg’s four path command kinds.
Segment: One step in a path traversal.
StrokeCap: Stroke line cap style.
StrokeJoin: Stroke line join style.
TextWrap: Text wrapping mode for a Text object.
WgTargetType: WebGPU target type.

Traits§

Canvas: Operations shared across SwCanvas, GlCanvas, and WgCanvas.
Paint: Common trait for all paint objects (Shape, Scene, Picture, Text).

Type Aliases§

Result: Specialized Result for ThorVG operations.

Crate thorvg

Crate thorvg Copy item path

§no_std Support

§Cargo Features

§Quick Start

Structs§

Enums§

Traits§

Type Aliases§

Crate thorvg

§`no_std` Support