Overview

Relevant source files

• CONTRIBUTING.md
• README.md
• examples/Capi.cpp
• inc/thorvg.h
• src/bindings/capi/thorvg_capi.h
• src/bindings/capi/tvgCapi.cpp

Purpose and Scope

This document provides a high-level introduction to ThorVG, an open-source vector graphics rendering library designed for creating and rendering vector-based scenes and animations. This page covers ThorVG's core capabilities, supported formats, multi-backend rendering architecture, API structure, and modular build system.

For detailed information about specific subsystems:

• Architecture details: see Architecture Overview
• Core C++ API: see Core API
• Lottie animation system: see Lottie Animation System
• SVG support: see SVG Loader
• Rendering engines: see Rendering Engines
• Build configuration: see Build System

What is ThorVG

ThorVG (Thor Vector Graphics) is a lightweight, high-performance graphics library that renders vector shapes, images, and animations to pixel buffers. The library is designed with a philosophy of simplicity and reliability, providing intuitive interfaces while maintaining a compact binary footprint (starting from ~150KB for minimal builds). The name "Thor" symbolizes both immense strength (performance) and lightning-fast agility (efficiency).

Sources: README.md26-31

Core Capabilities

ThorVG supports a comprehensive set of vector graphics primitives and operations:

Capability	Description
Lines & Shapes	Rectangles, circles, arbitrary paths with coordinate control
Filling	Solid colors, linear gradients, radial gradients, path clipping
Stroking	Width, joins, caps, dash patterns, trimming
Scene Management	Retainable scene graph with hierarchical transformations
Composition	Blending modes, masking, alpha compositing
Text	Unicode characters, multi-line layout, scalable TTF fonts
Images	SVG, JPG, PNG, WebP, raw bitmaps
Effects	Blur, drop shadow, fill, tint, tritone, color replacement
Animations	Lottie format with expressions and slots

Sources: README.md33-44

Supported Formats

Vector Formats

• SVG: Implements SVG Tiny Specification for lightweight, embedded-friendly SVG rendering. Supports most SVG Tiny features except animation, interactivity, and multimedia.
• Lottie: JSON-based animation format with support for expressions, slots, markers, and segments. Provides industry-standard vector animation playback.

Raster Formats

• PNG: Via libpng (external) or built-in static loader
• JPG: Via libjpeg-turbo (external) or built-in static loader
• WebP: Via libwebp (external)
• Raw Pixels: Direct ARGB8888 bitmap data

Sources: README.md321-356 README.md592-601

Multi-Backend Rendering Architecture

ThorVG implements a pluggable rendering backend system via the RenderMethod interface defined in src/renderer/tvgRender.h Applications select a backend at canvas creation time:

Diagram: Backend Architecture and Code Entities

Backend Characteristics

Backend	Implementation Files	Optimization Strategy	Use Case
Software	src/renderer/sw_engine/	RLE encoding + SIMD (AVX/NEON)	Embedded systems, IoT, guaranteed portability
OpenGL	src/renderer/gl_engine/	GPU tessellation + 50+ shader pipelines	Desktop, mobile with OpenGL ES 3.0+
WebGPU	src/renderer/wg_engine/	Compute/render pipelines + bind groups	Web browsers, cross-platform GPU (Metal/Vulkan/DX)

Sources: README.md83-97 src/renderer/tvgRender.h src/renderer/sw_engine/ src/renderer/gl_engine/ src/renderer/wg_engine/

API Structure and Core Abstractions

ThorVG's API is organized around fundamental abstractions defined in inc/thorvg.h1-2000 The library uses factory methods (::gen()) for object creation and follows the pimpl idiom with Paint::Impl.

Diagram: Core API Class Hierarchy and Factory Methods

Paint Class Hierarchy

All drawable objects inherit from tvg::Paint inc/thorvg.h349-696 which uses the pimpl idiom:

• tvg::Shape inc/thorvg.h697-1037: Vector paths with moveTo(), lineTo(), cubicTo() commands
• tvg::Picture inc/thorvg.h1038-1327: Loaded images (SVG, PNG, JPG, WebP) and raw pixel data
• tvg::Scene inc/thorvg.h1328-1546: Container for hierarchical composition with push() for scene effects
• tvg::Text inc/thorvg.h1547-1737: Scalable text rendering using TTF fonts via font(), text(), size()
• tvg::Animation inc/thorvg.h1738-1873: Frame-based animation controller with frame() and totalFrame()

Each Paint contains a Paint::Impl* pImpl inc/thorvg.h695 managing transform matrices, opacity (0-255), masks, blend modes, and clipping.

Sources: inc/thorvg.h1-2000 README.md220-317

Content Loading Pipeline

ThorVG separates format parsing from scene graph construction through a two-phase loader architecture. Each loader is conditionally compiled via THORVG_*_LOADER_SUPPORT defines in config.h.

Diagram: Loader Pipeline and Code Entities

Loader Architecture

Each loader implements a two-phase process:

1. Parsing Phase: Format-specific parser converts file data to intermediate model

   • SVG: simpleXmlParse() → SvgNode* tree src/loaders/svg/tvgXmlParser.cpp
   • Lottie: parseComposition() → LottieComposition src/loaders/lottie/tvgLottieParser.cpp
   • Images: External decoders → RenderSurface pixel buffer src/renderer/tvgRender.h
   • Fonts: FreeType → glyph vector paths src/loaders/ttf/tvgTtfParser.cpp

2. Building Phase: Intermediate model converted to Paint scene graph

   • SVG: svgSceneBuild() traverses SvgNode tree src/loaders/svg/tvgSvgSceneBuilder.cpp
   • Lottie: LottieBuilder::build() and update() for frame interpolation src/loaders/lottie/tvgLottieBuilder.cpp
   • Images: Direct RenderSurface attachment via Picture::load()
   • Fonts: Glyph outlines converted to Shape::appendPath() commands

Sources: src/loaders/svg/tvgSvgLoader.cpp src/loaders/lottie/tvgLottieLoader.cpp src/loaders/png/tvgPngLoader.cpp src/loaders/jpg/tvgJpgLoader.cpp src/loaders/ttf/tvgTtfLoader.cpp src/loaders/svg/tvgXmlParser.cpp src/loaders/lottie/tvgLottieParser.cpp src/loaders/svg/tvgSvgSceneBuilder.cpp src/loaders/lottie/tvgLottieBuilder.cpp

Rendering Pipeline

The rendering process follows a three-phase pattern consistent across all backends: update preparation, asynchronous drawing, and synchronization.

Diagram: Rendering Pipeline Methods and Phases

Rendering Phases

1. Update Phase (canvas->update()): Calls Paint::Impl::update() src/renderer/tvgPaint.cpp to traverse scene graph and invoke Paint::Impl::prepare() which generates backend-agnostic RenderShape and RenderSurface data structures src/renderer/tvgRender.h

2. Draw Phase (canvas->draw()): Dispatches backend-specific tasks:

   • SW: SwTask queued to thread pool src/renderer/sw_engine/tvgSwRenderer.cpp
   • GL: GlRenderTask hierarchy built src/renderer/gl_engine/tvgGlRenderTask.cpp
   • WG: WgRenderData prepared for command encoding src/renderer/wg_engine/tvgWgRenderer.cpp

3. Sync Phase (canvas->sync()): Blocks until rendering completes and flushes to target buffer/FBO/texture. Required before accessing rendered pixels or modifying canvas state.

Sources: src/renderer/tvgPaint.cpp src/renderer/tvgRender.h src/renderer/sw_engine/tvgSwRenderer.cpp src/renderer/gl_engine/tvgGlRenderer.cpp src/renderer/gl_engine/tvgGlRenderTask.cpp src/renderer/wg_engine/tvgWgRenderer.cpp

Modular Build System

ThorVG uses Meson with fine-grained feature control via meson_options.txt options that generate preprocessor defines in builddir/config.h. This enables builds ranging from ~150KB (minimal) to ~1MB (full features).

Diagram: Build System Configuration Flow

Build Option Categories

Option	Values	Generated Defines	Affects
engines	sw, gl, wg, all	THORVG_SW_RASTER_SUPPORT, THORVG_GL_RASTER_SUPPORT, THORVG_WG_RASTER_SUPPORT	src/renderer/sw_engine/ src/renderer/gl_engine/ src/renderer/wg_engine/
loaders	svg, lottie, png, jpg, ttf, webp, all	THORVG_SVG_LOADER_SUPPORT, THORVG_LOTTIE_LOADER_SUPPORT, etc.	src/loaders/ subdirectories
savers	tvg, gif	THORVG_TVG_SAVER_SUPPORT, THORVG_GIF_SAVER_SUPPORT	src/savers/tvg/ src/savers/gif/
bindings	capi, wasm_beta	THORVG_CAPI_BINDING_SUPPORT, THORVG_WASM_BINDING_SUPPORT	src/bindings/capi/ src/bindings/wasm/
extra	expressions (default)	THORVG_LOTTIE_EXPRESSIONS_SUPPORT	src/loaders/lottie/jerryscript/

Example Build Configurations

Each configuration produces a single libthorvg.so or libthorvg.a containing only the selected features, enabling optimal size for target platforms.

Sources: meson_options.txt meson.build src/lib/meson.build README.md356-373

Platform Support

ThorVG is designed for portability across diverse platforms:

Platform Category	Platforms	Typical Configuration
Desktop	Linux, Windows, macOS	Full build with GL/WG engines
Mobile	iOS, Android	SW/GL engines, Lottie loader
Web	Browsers via Emscripten	WASM with SW/WG engines
Embedded	IoT devices, MCUs	Minimal SW engine, no threading

Real-world integrations include:

• Canva iOS: 80% rendering performance improvement
• Godot Engine: Vector UI resources
• LVGL: Embedded GUI framework
• dotLottie Player: Web animation playback
• ESP-IDF: Official Espressif component for ESP32 devices

Sources: README.md99-104 README.md399-456

Threading and Smart Rendering

Threading Model

ThorVG implements a task scheduler based on thread pools that handles encoding, decoding, updating, and rendering tasks. The threading system is configurable via Initializer::init(threads) and is optional—applications can run ThorVG single-threaded for simpler integration.

Partial Rendering

ThorVG supports smart partial rendering by tracking modified regions (dirty rectangles) and updating only changed portions of the scene. This optimization is particularly effective for:

• UI rendering with static backgrounds
• Design tools with localized edits
• Mobile and embedded systems (energy efficiency)

Partial rendering provides minimal benefit for highly dynamic content like full-screen animations or games where most objects change every frame.

Sources: README.md62-81

API Bindings

ThorVG provides language bindings beyond the core C++ API through wrapper layers that preserve zero-overhead delegation.

C API

Defined in src/bindings/capi/thorvg_capi.h1-730 and implemented in src/bindings/capi/tvgCapi.cpp Uses opaque pointer types (Tvg_Canvas, Tvg_Paint) with reinterpret_cast to underlying C++ classes:

Implementation pattern in src/bindings/capi/tvgCapi.cpp350-353:

Enables FFI integration with Dart/Flutter, Nim, D, and other languages that support C calling conventions.

WASM Bindings

Defined in src/bindings/wasm/thorvg_wasm.cpp using Emscripten's EMSCRIPTEN_BINDINGS macro. Exposes TvgLottieAnimation class to JavaScript:

• Engine selection via TvgEngineMethod enum (SW/GL/WG)
• load() from ArrayBuffer or URL string
• Frame control via frame() and totalFrame()
• Pixel data access via render() to TypedArray
• Asset resolution callbacks for external resources
• Published as @thorvg/lottie-player npm package

Sources: src/bindings/capi/thorvg_capi.h1-730 src/bindings/capi/tvgCapi.cpp src/bindings/wasm/thorvg_wasm.cpp README.md581-587

Basic Usage Example

The following demonstrates the essential API workflow:

Sources: README.md220-317