thorvg

# ThorVG

**Thor Vector Graphics** is a **production-ready** vector graphics engine designed for creating **interactive apps** and **creative tools**. It combines **high performance** with **lightweight efficiency**, as Thor embodies a dual meaning—symbolizing both immense strength and lightning-fast agility. Embracing the philosophy of simplicity leads to reliability, the ThorVG project provides easy, **user-friendly interfaces** while maintaining a **compact footprint** and **minimal overhead**.

The following primitives are supported by ThorVG:
- **Lines & Shapes**: rectangles, circles, paths, and arbitrary vector geometry - **Filling**: solid colors and linear & radial gradients - **Stroking**: stroke width, joins, caps, dash patterns, and trimming - **Scene Management**: retained-mode scene graph and hierarchical transformations - **Composition**: W3C compositing and blending modes, masking, clipping, and nested scenes - **Text**: Unicode, scalable TTF/OTF fonts, and multi-line text layout - **Images**: SVG, PNG, JPEG, WebP, and raw bitmaps - **Effects**: blur, drop shadow, tint, tritone, color replacement, and fill effects - **Animations**: Lottie (JSON) playback and rendering

### Lightweight Design ​ThorVG is designed for a wide range of programs, offering adaptability for integration and use in various applications and systems. It achieves this through a single binary with selectively buildable, modular components in a building block style. This ensures both optimal size and easy maintenance.

The core library of ThorVG maintains a binary size of approximately **170KB**. This is significantly smaller compared to graphics engines designed primarily for desktop environments and offers the following advantages.
- **Memory Efficiency**: Thanks to its low runtime memory usage, ThorVG operates stably even on low-spec systems. - **Fast Boot**: The library loads and initializes quickly, improving the overall startup speed of applications. - **Low Size Deployment:** With its small code and resource footprint, ThorVG is well-suited for embedded systems, IoT devices, and network-constrained environments. ### Broad Portability ThorVG is based on the **C++** standard and provides consistent functionality across various platforms through an abstraction layer that minimizes dependence on specific operating systems or hardware.
- **Extensive Platform Support**: ThorVG supports web platforms, desktop operating systems such as Windows, macOS, and Linux, mobile platforms including Android and iOS, as well as embedded systems like Tizen and RTOS-based environments. - **Microcontroller Support**: ThorVG has been shown to run on microcontrollers like the ESP32, demonstrating its efficiency even within environments with highly limited memory and storage. - **Headless Rendering Support**: ThorVG can perform rendering without a display server, enabling use cases such as server-side graphics processing or offline rendering tools. If your program includes the main renderer, you can seamlessly utilize ThorVG APIs by transitioning drawing contexts between the main renderer and ThorVG. Throughout these API calls, ThorVG effectively serializes drawing commands among volatile paint nodes. Subsequently, it undertakes synchronous or asynchronous rendering via its render-backend engines. Additionally, ThorVG is adept at handling vector images, including formats like SVG and Lottie, and it remains adaptable for accommodating additional popular formats as needed. In the rendering process, the library may generate intermediate frame buffers for scene compositing, though only when essential. The accompanying diagram provides a concise overview of how to effectively incorporate ThorVG within your system.

### CPU Rasterization ThorVG is optimized for CPU-based rasterization, with a strong focus on vector rendering in environments where GPU resources are limited, unavailable, or intentionally avoided. In representative CPU benchmarks, ThorVG demonstrates **an average of ~2.9× faster performance** to a widely-used vector graphics engine across common vector rendering workloads. The advantage is particularly clear in geometry-heavy scenarios such as rectangles, strokes, rotations, and circle rendering. #### Performance Overview

#### Test Conditions - Tested with 5k semi-transparent primitives, including shapes, strokes, and images, using alpha blending. - Image filtering was performed using bilinear interpolation. - Test Platform: Apple M2 Pro (macOS 26) - Render size: 2560 × 1440 (2K) for each test case - Versions: ThorVG v1.1, Skia v148

### Threading ThorVG incorporates a threading mechanism designed to seamlessly retrieve upcoming scenes without unnecessary delays. It utilizes a finely-tuned task scheduler based on thread pools to handle a variety of tasks, including encoding, decoding, updating, and rendering. This architecture ensures efficient use of multi-core processing.

The task scheduler is carefully designed to abstract complexity, simplify integration, and enhance user convenience. Its use is optional, allowing users to adopt it based on their specific needs.

### Smart Rendering ThorVG supports smart partial rendering, which enables more efficient rendering workflows by updating only the portions of a vector scene that have changed. By internally tracking modified regions, it minimizes unnecessary redraws and optimizes overall performance. This feature provides significant benefits in scenarios such as UI rendering, design tools, or applications where large parts of the scene remain static and only small elements update between frames. In such cases, avoiding full-scene rendering can greatly reduce computational workload and improve energy efficiency—making it particularly valuable on mobile and embedded systems.

The following figure illustrates the geometry changes and highlights the minimal redraw region (outlined in red) that needs to be updated. Only the modified area between the previous and current frames is selectively redrawn, significantly improving performance.

Please note that in highly dynamic content—such as fast-paced games or full-screen animations where nearly all objects change every frame—partial rendering provides little to no benefit and may even introduce minor overhead. In these scenarios, full-scene rendering is typically the better choice. For a practical showcase, visit [this page](https://hermet.github.io/partial-test/) demonstrating a performance comparison of partial rendering using ThorVG's software renderer.
### Render Backends Today, ThorVG provides its own implementation of multiple rendering backends, allowing you to choose the one that best suits your application and target platform.
- CPU/SIMD (Software) - OpenGL/ES - WebGL - WebGPU ThorVG is particularly ahead of the curve in the web ecosystem. WebGPU introduces a next-generation graphics API comparable to Vulkan, providing low-overhead GPU access and modern graphics capabilities. This enables more aggressive optimization strategies while preserving feature parity with other ThorVG backends. All vector rendering features are fully supported on the WebGPU backend, ensuring a consistent rendering experience across platforms. Beyond feature completeness, the WebGPU backend also delivers substantial performance improvements over the OpenGL backend in many rendering workloads. Internal benchmarks show up an average of approximately **1.8× higher** rendering throughput, with the largest gains observed in stroke rendering, gradients, and image rendering. Even for general vector rendering, WebGPU consistently maintains higher performance while producing identical visual output.

> [!NOTE] > Benchmark results were obtained using [ThorVG's benchmark application](https://github.com/thorvg/thorvg.benchmark) on Apple M1. Actual performance may vary depending on the hardware, operating system, graphics driver, and rendering workload. Furthermore, by abstracting native graphics APIs such as Metal, Vulkan, and DirectX through WebGPU, ThorVG provides a single rendering interface that seamlessly scales across desktop, mobile, and web environments. This architecture allows applications to benefit from modern GPU capabilities without requiring platform-specific rendering code.

### Supported Platforms ThorVG is designed to be portable across a wide range of devices, including small IoT devices, embedded systems, mobile platforms, game consoles, desktop environments, and the web. It is actively under development, with continuous efforts to expand support for essential platforms as needed. Currently, the major supported platforms include:

## Contents - [ThorVG](#thorvg) - [Installation](#installation) - [Build and Install](#build-and-install) - [Build with Visual Studio](#build-with-visual-studio) - [Build with Xcode](#build-with-xcode) - [Quick Start](#quick-start) - [SVG](#svg) - [Lottie](#lottie) - [In Practice](#in-practice) - [ThorVG Demo](#thorvg-demo) - [Examples](#examples) - [C++ Examples](#c-examples) - [Playground](#playground) - [Tools](#tools) - [ThorVG View](#thorvg-view) - [VS Code LiveView](#vs-code-liveview) - [CLI Tools](#cli-tools) - [Related Projects](#related-projects) - [API Bindings](#api-bindings) - [Documentation](#documentation) - [References](#references) - [Dependencies](#dependencies) - [Contributors](#contributors) - [Partners](#partners) - [Sponsors](#sponsors) - [Communication](#communication) [](#contents)
## Installation This section details the steps required to configure the environment for installing ThorVG.

### Build and Install ThorVG supports [meson](https://mesonbuild.com/) build system. Install [meson](http://mesonbuild.com/Getting-meson.html) and [ninja](https://ninja-build.org/) if you don't have them already. Run meson to configure ThorVG in the thorvg root folder. ``` meson setup builddir ``` Run ninja to build & install ThorVG: ``` ninja -C builddir install ``` Regardless of the installation, all build results (symbols, executable) are generated in the builddir folder in thorvg. Some results such as examples won't be installed, you can check More examples section to see how to change it.
​
Note that some systems might include ThorVG package as a default component. In that case, you can skip this manual installation.
### Build with Visual Studio If you want to create Visual Studio project files, use the command `--backend=vs`. The resulting solution file `thorvg.sln` will be located in the build folder. ``` meson setup builddir --backend=vs ``` ### Build with Xcode If you want to create Xcode project files, use the command `--backend=xcode`. The resulting solution file `thorvg.xcodeproj` will be located in the build folder. ``` meson setup builddir --backend=xcode ``` [Back to contents](#contents)

## Quick Start ThorVG renders vector shapes to a given canvas buffer. The following is a quick start to show you how to use the essential APIs. First, you should initialize the ThorVG engine: ```cpp tvg::Initializer::init(4); //4 threads ``` Then it would be best if you prepared an empty canvas for drawing on it: ```cpp static uint32_t buffer[WIDTH * HEIGHT]; //canvas target buffer auto canvas = tvg::SwCanvas::gen(); //generate a canvas canvas->target(buffer, WIDTH, WIDTH, HEIGHT, tvg::ColorSpace::ARGB8888); //buffer, stride, w, h, Colorspace ``` Next you can