README.md

   1 [![Continuous-integration](https://github.com/Samsung/thorvg/actions/workflows/actions.yml/badge.svg)](https://github.com/Samsung/thorvg/actions/workflows/actions.yml)
   2 [![Gitter](https://badges.gitter.im/thorvg/community.svg)](https://gitter.im/thorvg/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
   3
   4 # ThorVG
   5
   6 <p align="center">
   7   <img width="500" height="346" src="https://github.com/Samsung/thorvg/blob/master/res/thorvg_card2.png">
   8 </p>
   9
  10 ThorVG is a platform-independent portable library for drawing vector-based scene and animation. It's an open-source software that is freely used by a variety of software platforms and applications. ThorVG provides neat and easy APIs, its library has no dependencies and keeps cheat and super compact size. It serves as the vector graphics engine for Tizen OS that powers many products. <br />
  11 <br />
  12 The following list shows primitives that are supported by ThorVG: <br />
  13  - Shapes: Line, Arc, Curve, Path, Polygon, ...
  14  - Filling: Solid, Linear and Radial Gradient
  15  - Scene Graph & Affine Transformation (translation, rotation, scale, ...)
  16  - Stroking: Width, Join, Cap, Dash
  17  - Composition: Blending, Masking, Path Clipping, ...
  18  - Pictures: SVG, PNG, Bitmap, ...
  19 <p align="center">
  20   <img width="930" height="473" src="https://github.com/Samsung/thorvg/blob/master/res/example_primitives.png">
  21 </p>
  22 <br />
  23 Your program could call neat TVG APIs while switching drawing context If you have your own drawing engine. During the API calls, ThorVG serializes drawing commands among the volatile paints' nodes then performs synchronous/asynchronous rendering using own backend raster engines. ThorVG supports vector images such as SVG, also expand supporting other popular formats on demand. On the rendering, it could spawn intermediate frame-buffers for compositing scenes only when it's necessary. The next figure shows you a brief strategy on how to use ThorVG on your system.<br />
  24 <br />
  25 <p align="center">
  26   <img width="900" height="288" src="https://github.com/Samsung/thorvg/blob/master/res/example_flow.png">
  27 </p>
  28 <br />
  29
  30 ## Contents
  31 - [Building ThorVG](#building-thorvg)
  32         - [Meson Build](#meson-build)
  33 - [Quick Start](#quick-start)
  34 - [SVG](#svg)
  35 - [Practices](#practices)
  36         - [Tizen](#tizen)
  37         - [Rive](#rive)
  38 - [Examples](#examples)
  39 - [Tools](#tools)
  40         - [ThorVG Viewer](#thorvg-viewer)
  41         - [SVG to PNG](#svg-to-png)
  42 - [API Bindings](#api-bindings)
  43 - [Issues or Feature Requests](#issues-or-feature-requests)
  44
  45 [](#contents)
  46 <br />
  47 ## Building ThorVG
  48 ThorVG supports [meson](https://mesonbuild.com/) build system.
  49 <br />
  50 ### Meson Build
  51 Install [meson](http://mesonbuild.com/Getting-meson.html) and [ninja](https://ninja-build.org/) if not already installed.
  52
  53 Run meson to configure ThorVG:
  54 ```
  55 meson build
  56 ```
  57 Run ninja to build & install ThorVG:
  58 ```
  59 ninja -C build install
  60 ```
  61 [Back to contents](#contents)
  62 <br />
  63 <br />
  64 ## Quick Start
  65 ThorVG renders vector shapes to a given canvas buffer. The following is a quick start to show you how to use the basic APIs.
  66
  67 First, you should initialize the ThorVG engine:
  68
  69 ```cpp
  70 tvg::Initializer::init(tvg::CanvasEngine::Sw, 0);   //engine method, thread count
  71 ```
  72
  73 Then you should prepare an empty canvas for drawing on it:
  74
  75 ```cpp
  76 static uint32_t buffer[WIDTH * HEIGHT];                                 //canvas target buffer
  77
  78 auto canvas = tvg::SwCanvas::gen();                                     //generate a canvas
  79 canvas->target(buffer, WIDTH, WIDTH, HEIGHT, tvg::SwCanvas::ARGB8888);  //buffer, stride, w, h, Colorspace
  80 ```
  81
  82 Next you can draw multiple shapes on the canvas:
  83
  84 ```cpp
  85 auto rect = tvg::Shape::gen();               //generate a shape
  86 rect->appendRect(50, 50, 200, 200, 20, 20);  //define it as a rounded rectangle (x, y, w, h, rx, ry)
  87 rect->fill(100, 100, 100, 255);              //set its color (r, g, b, a)
  88 canvas->push(move(rect));                    //push the rectangle into the canvas
  89
  90 auto circle = tvg::Shape::gen();             //generate a shape
  91 circle->appendCircle(400, 400, 100, 100);    //define it as a circle (cx, cy, rx, ry)
  92
  93 auto fill = tvg::RadialGradient::gen();      //generate a radial gradient
  94 fill->radial(400, 400, 150);                 //set the radial gradient geometry info (cx, cy, radius)
  95
  96 tvg::Fill::ColorStop colorStops[2];          //gradient colors
  97 colorStops[0] = {0.0, 255, 255, 255, 255};   //1st color values (offset, r, g, b, a)
  98 colorStops[1] = {1.0, 0, 0, 0, 255};         //2nd color values (offset, r, g, b, a)
  99 fill->colorStops(colorStops, 2);             //set the gradient colors info
 100
 101 circle->fill(move(fill));                    //set the circle fill
 102 canvas->push(move(circle));                  //push the circle into the canvas
 103
 104 ```
 105
 106 This code generates the following result:
 107
 108 <p align="center">
 109   <img width="416" height="411" src="https://github.com/Samsung/thorvg/blob/master/res/example_shapes.png">
 110 </p>
 111
 112 You can also draw you own shapes and use dashed stroking:
 113
 114 ```cpp
 115 auto path = tvg::Shape::gen();               //generate a path
 116 path->moveTo(199, 34);                       //set sequential path coordinates
 117 path->lineTo(253, 143);
 118 path->lineTo(374, 160);
 119 path->lineTo(287, 244);
 120 path->lineTo(307, 365);
 121 path->lineTo(199, 309);
 122 path->lineTo(97, 365);
 123 path->lineTo(112, 245);
 124 path->lineTo(26, 161);
 125 path->lineTo(146, 143);
 126 path->close();
 127
 128 path->fill(150, 150, 255, 255);              //path color
 129
 130 path->stroke(3);                             //stroke width
 131 path->stroke(0, 0, 255, 255);                //stroke color
 132 path->stroke(tvg::StrokeJoin::Round);        //stroke join style
 133 path->stroke(tvg::StrokeCap::Round);         //stroke cap style
 134
 135 float pattern[2] = {10, 10};                 //stroke dash pattern (line, gap)
 136 path->stroke(pattern, 2);                    //set the stroke pattern
 137
 138 canvas->push(move(path));                    //push the path into the canvas
 139
 140 ```
 141
 142 The code generates the following result:
 143
 144 <p align="center">
 145   <img width="300" height="300" src="https://github.com/Samsung/thorvg/blob/master/res/example_path.png">
 146 </p>
 147
 148 Now begin rendering & finish it at a particular time:
 149
 150 ```cpp
 151 canvas->draw();
 152 canvas->sync();
 153 ```
 154
 155 Then you can acquire the rendered image from the buffer memory.
 156
 157 Lastly, terminate the engine after its usage:
 158
 159 ```cpp
 160 tvg::Initializer::term(tvg::CanvasEngine::Sw);
 161 ```
 162 [Back to contents](#contents)
 163 <br />
 164 <br />
 165 ## SVG
 166
 167 ThorVG supports SVG (Scalable Vector Graphics) rendering through its own SVG interpreter. It satisfies the [SVG Tiny Specification](https://www.w3.org/TR/SVGTiny12/)
 168 in order to keep it lightweight, so it's useful for the embedded systems. Among the SVG Tiny specs, unsupported features in the ThorVG are the following:
 169
 170  - Animation
 171  - Fonts & Text
 172  - Interactivity
 173  - Multimedia
 174  - Scripting
 175
 176 The following code snippet shows how to draw SVG image using ThorVG:
 177
 178 ```cpp
 179 auto picture = tvg::Picture::gen();         //generate a picture
 180 picture->load("tiger.svg");                 //load SVG file
 181 canvas->push(move(picture));                //push the picture into the canvas
 182 ```
 183
 184 The result:
 185
 186 <p align="center">
 187   <img width="300" height="300" src="https://github.com/Samsung/thorvg/blob/master/res/example_tiger.png">
 188 </p>
 189
 190 [Back to contents](#contents)
 191 <br />
 192 <br />
 193 ## Practices
 194 ### Tizen
 195 ThorVG is integrated into the [Tizen](https://www.tizen.org) platform as the vector graphics engine. It's being used for vector primitive drawings
 196 and scalable image contents such as SVG and Lottie Animation among the Tizen powered products.
 197
 198 <p align="center">
 199   <img width="798" height="285" src="https://github.com/Samsung/thorvg/blob/master/res/example_tizen.png">
 200 </p>
 201
 202 [Back to contents](#contents)
 203 <br />
 204 <br />
 205 ### Rive
 206 We're also building a [Rive](https://rive.app/) port which supports Rive Animation run through the ThorVG backend. Rive is a brand new animation platform
 207 that supports fancy, user interactive vector animations. For more details see [Rive-Tizen](https://github.com/rive-app/rive-tizen) on [Github](https://github.com/rive-app/).
 208
 209 <p align="center">
 210   <img width="600" height="324" src="https://github.com/Samsung/thorvg/blob/master/res/example_rive.gif">
 211 </p>
 212
 213 [Back to contents](#contents)
 214 <br />
 215 <br />
 216 ## Examples
 217 There are various examples available in `thorvg/src/examples`, to help you understand ThorVG APIs.
 218
 219 To execute these examples, you can build them with the following meson option:
 220 ```
 221 meson -Dexamples=true . build
 222 ```
 223 Note that these examples require the EFL `elementary` package for launching. If you're using Linux-based OS, you can easily
 224 install this package from your OS distribution server. Otherwise, please visit the official [EFL page](https://enlightenment.org/) for more information.
 225
 226 [Back to contents](#contents)
 227 <br />
 228 <br />
 229 ## Tools
 230 ### ThorVG Viewer
 231 [ThorVG viewer](https://samsung.github.io/thorvg.viewer) supports immediate rendering through your browser. You can drag & drop SVG files on the page
 232 and see the rendering result on the spot.
 233
 234 [Back to contents](#contents)
 235 <br />
 236 <br />
 237 ### SVG to PNG
 238 ThorVG provides an executable `svg2png` converter which generates a PNG file from an SVG file.
 239
 240 To use `svg2png`, you must turn on this feature in the build option:
 241 ```
 242 meson -Dtools=svg2png . build
 243 ```
 244 Alternatively, you can add the `svg2png` value to the `tools` option in `meson_option.txt`. The build output will be located in `{builddir}/src/bin/svg2png/`.
 245
 246 Examples of the usage of the `svg2png`:
 247 ```
 248 Usage:
 249    svg2png [svgFileName] [Resolution] [bgColor]
 250
 251 Examples:
 252     $ svg2png input.svg
 253     $ svg2png input.svg 200x200
 254     $ svg2png input.svg 200x200 ff00ff
 255 ```
 256 [Back to contents](#contents)
 257 <br />
 258 <br />
 259 ## API Bindings
 260 Our main development APIs are written in C++ but ThorVG also provides API bindings for C.
 261
 262 [Back to contents](#contents)
 263 <br />
 264 <br />
 265 ## Issues or Feature Requests
 266 For support please reach us in [Gitter](https://gitter.im/thorvg/community).