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