# thorvg-rs
> **⚠️ Work in progress** — This crate is under active development and not yet ready for production use. APIs may change without notice.
Rust bindings for [ThorVG](https://github.com/thorvg/thorvg), a production-ready vector graphics engine supporting SVG, Lottie animations, shapes, text, gradients, effects, and more.
## Crates
| [`thorvg-sys`](thorvg-sys/) | Raw FFI bindings generated by bindgen |
| [`thorvg`](thorvg/) | Safe, idiomatic Rust wrapper |
## Quick Start
```rust
use thorvg::{Thorvg, SwCanvas, Shape, ColorSpace};
let _engine = Thorvg::init(0).unwrap();
let mut canvas = SwCanvas::new(Default::default()).unwrap();
let mut buffer = vec![0u32; 800 * 600];
canvas.set_target(&mut buffer, 800, 800, 600, ColorSpace::ABGR8888).unwrap();
let mut shape = Shape::new();
shape.append_rect(10.0, 10.0, 200.0, 150.0, 10.0, 10.0, true).unwrap();
shape.set_fill_color(255, 0, 0, 255).unwrap();
canvas.push(shape).unwrap();
canvas.draw(true).unwrap();
canvas.sync().unwrap();
// buffer now contains rendered pixels
```
## Features
### `thorvg` (safe wrapper)
| `std` | ✅ | File I/O APIs (`Picture::load`, `Text::load_font`, etc.) |
| `vendored` | ✅ | Build ThorVG from source via the `cc` crate |
| `lottie` | ✅ | Lottie animation loader |
| `svg` | ✅ | SVG loader |
| `png` | ✅ | Built-in PNG loader (lodepng, no system dep) |
| `fonts` | ✅ | SFNT / OTF / TTF font loaders |
| `expressions` | ✅ | Lottie expressions via JerryScript (~200 KB RAM) |
| `threads` | ✅ | Multi-threaded TaskScheduler (`std::thread`) |
| `file-io` | ✅ | Filesystem I/O support in ThorVG |
All features are pass-throughs to `thorvg-sys`.
### Desktop (default — everything enabled)
```toml
[dependencies]
thorvg = "0.1"
```
### Embedded / `no_std` (pick only what you need)
```toml
[dependencies]
thorvg = { version = "0.1", default-features = false, features = ["vendored", "lottie", "svg"] }
```
This gives you Lottie + SVG playback with no threads, no JerryScript,
no PNG/font loaders — suitable for microcontrollers with limited RAM.
## Cross-Compilation
ThorVG is compiled from C++ source using the [`cc`](https://crates.io/crates/cc) crate, which
automatically picks up the correct cross-compiler from Cargo's target
environment. No meson or ninja required.
Tested targets:
| `x86_64-unknown-linux-gnu` | `g++` / `clang++` | Desktop default |
| `xtensa-esp32s3-espidf` | `xtensa-esp32s3-elf-g++` | ESP32-S3 (Waveshare Knob Touch S3) |
| `xtensa-esp32-espidf` | `xtensa-esp32-elf-g++` | ESP32 |
| `riscv32imc-esp-espidf` | `riscv32-esp-elf-g++` | ESP32-C6 |
| `thumbv8m.main-none-eabihf` | `arm-none-eabi-g++` | RP2350 / Cortex-M33 |
For Xtensa targets, the build script automatically selects the correct
target-specific compiler wrapper (e.g. `xtensa-esp32s3-elf-g++`) to
ensure the right endianness and ABI.
## API Coverage
100% of the ThorVG C API surface (158 functions) is wrapped:
- **Canvas** — `SwCanvas`, `GlCanvas`, `WgCanvas`
- **Paint** — opacity, visibility, transforms, clipping, masking, blending, hit-testing
- **Shape** — paths, rectangles, circles, fill, stroke, gradients, trim path
- **Gradient** — linear, radial, color stops, spread, transforms
- **Picture** — load SVG/PNG/JPG/WebP/Lottie from file or memory
- **Scene** — grouping, effects (blur, drop shadow, fill, tint, tritone)
- **Text** — font loading, styling, wrapping, metrics, outline
- **Animation** — frame control, segments, duration
- **LottieAnimation** — slots, markers, tweening, expressions, quality
- **Saver** — export paint/animation to file
- **Accessor** — scene tree traversal with callbacks
## `no_std` Support
Both crates are `no_std` compatible. The safe wrapper requires `alloc`.
File I/O APIs (`Picture::load`, `Text::load_font`, `Saver::save`) are
gated behind the `std` feature. All rendering, shapes, gradients,
scenes, and canvas operations work in `no_std`.
## Examples
```bash
cargo run --example shapes
cargo run --example stroke
cargo run --example gradient
cargo run --example scene
cargo run --example transforms
cargo run --example blending
cargo run --example opacity
cargo run --example clipping
cargo run --example masking
cargo run --example scene_effects
cargo run --example paths
cargo run --example picture_svg
cargo run --example paint_order
cargo run --example render_to_buffer
```
All examples output PNG files in the current directory.
## Building
ThorVG is vendored as a git submodule and compiled automatically via
the [`cc`](https://crates.io/crates/cc) crate. You need a C++ compiler
(any `g++` or `clang++` will do):
```bash
git clone --recurse-submodules https://github.com/goyox86/thorvg-rs
cd thorvg-rs
cargo build
```
No meson, ninja, or pkg-config required for vendored builds.
## Development
Requires [just](https://github.com/casey/just) for task running:
```bash
just ci-quick # fmt, clippy, test, no_std check
just ci # full CI: above + AddressSanitizer + ThreadSanitizer
just test-asan # run tests under AddressSanitizer
just examples # run all 14 examples
just coverage # show C API coverage stats
just --list # show all recipes
```
## Acknowledgments
This project provides Rust bindings to [ThorVG](https://github.com/thorvg/thorvg), created and maintained by the [ThorVG project](https://www.thorvg.org/) contributors. ThorVG is a [Linux Foundation](https://www.linuxfoundation.org/) project. All vector graphics rendering is performed by the ThorVG engine — this crate is a thin binding layer.
This project is not affiliated with, endorsed by, or sponsored by the ThorVG project or the Linux Foundation.
Special thanks to [Hermet Park](https://github.com/hermet) and all [ThorVG contributors](https://github.com/thorvg/thorvg/graphs/contributors) for building such an excellent, lightweight, and well-designed vector graphics engine with a clean C API that made these bindings possible.
## License
MIT — same as [ThorVG](https://github.com/thorvg/thorvg/blob/main/LICENSE).