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++, no dependencies and keeps super compact size. <br />
  11 <br />
  12 The next list shows drawing primitives ThorVG providing.<br />
  13  - Shapes: Line, Arc, Curve, Path, Polygon, etc
  14  - Filling: Solid, Linear, Radial Gradient
  15  - Scene Graph & Affine Transformation (translation, rotation, scale ...)
  16  - Stroking: Width, Join, Cap, Dash
  17  - Composition: Blending, Masking, Path Clipping, etc
  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), ThorVG serializes drawing commands among volatile paints node, performs sync/asynchronous rendering by its decent engines. The engine is suggested to immediate rendering method so that your system could adaptively integrate with it. ThorVG supports vector images such as SVG, also will support coming popular formats by demands. On rendering, it might introduce intermediate frame buffers for compositing vector scenes but only when it's necessary and these are temporarily used for saving memory. Next figure shows you a brief strategy how to use ThorVG in 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 Basically, 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 on a given canvas buffer. Here shows quick start to learn basic API usages.
  66
  67 First, You can initialize ThorVG engine.
  68
  69 ```cpp
  70 tvg::Initializer::init(tvg::CanvasEngine::Sw, 0);   //engine method, thread count
  71 ```
  72
  73 You can prepare a 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);    //stride, w, h
  80 ```
  81
  82 Next you can draw multiple shapes onto the canvas.
  83
  84 ```cpp
  85 auto rect = tvg::Shape::gen();               //generate a round rectangle
  86 rect->appendRect(50, 50, 200, 200, 20, 20);  //round geometry(x, y, w, h, rx, ry)
  87 rect->fill(100, 100, 0, 255);                //round rectangle color (r, g, b, a)
  88 canvas->push(move(rect));                    //push round rectangle drawing command
  89
  90 auto circle = tvg::Shape::gen();             //generate a circle
  91 circle->appendCircle(400, 400, 100, 100);    //circle geometry(cx, cy, radiusW, radiusH)
  92
  93 auto fill = tvg::RadialGradient::gen();      //generate radial gradient for circle fill
  94 fill->radial(400, 400, 150);                 //radial fill info(cx, cy, radius)
  95
  96 tvg::Fill::ColorStop colorStops[2];          //gradient color info
  97 colorStops[0] = {0, 255, 255, 255, 255};     //index, r, g, b, a (1st color value)
  98 colorStops[1] = {1, 0, 0, 0, 255};           //index, r, g, b, a (2nd color value)
  99 fill.colorStops(colorStop, 2);               //set fil with gradient color info
 100
 101 circle->fill(move(fill));                    //circle color
 102 canvas->push(move(circle));                  //push circle drawing command
 103
 104 ```
 105
 106 This code result looks like this.
 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 Or you can draw pathes with dash 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};
 136 path->stroke(pattern, 2);                    //stroke dash pattern (line, gap)
 137
 138 canvas->push(move(path));                    //push path drawing command
 139
 140 ```
 141
 142 This path drawing result shows like this.
 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 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 basically aims to satisfy with [SVG Tiny Specification](https://www.w3.org/TR/SVGTiny12/) for the lightweight system such as embeded. Most cases ThorVG supports the SVG spec fully but some partial SVG features were not supported officially yet. Next list shows the unsupported features by ThorVG.
 168
 169  - CSS Styles
 170  - Filters
 171  - Images
 172
 173 Next code snippet shows you how to draw SVG image using ThorVG.
 174
 175 ```cpp
 176 auto picture = tvg::Picture::gen();         //generate a picture
 177 picture->load("tiger.svg");                 //Load SVG file.
 178 canvas->push(move(picture));                //push picture drawing command
 179 ```
 180
 181 And here is the result.
 182
 183 <p align="center">
 184   <img width="300" height="300" src="https://github.com/Samsung/thorvg/blob/master/res/example_tiger.png">
 185 </p>
 186
 187 [Back to contents](#contents)
 188 <br />
 189 <br />
 190 ## Practices
 191 ### Tizen
 192 ThorVG is integrated in [Tizen](https://www.tizen.org) platform as the vector graphics engine, it's being used for vector primitive drawings and scalable image contents such as SVG, Lottie Animation among the Tizen powered products.
 193
 194 <p align="center">
 195   <img width="798" height="285" src="https://github.com/Samsung/thorvg/blob/master/res/example_tizen.png">
 196 </p>
 197
 198 [Back to contents](#contents)
 199 <br />
 200 <br />
 201 ### Rive
 202 We're also building a [Rive](https://rive.app/) port which supports Rive Animation run through ThorVG backend. Rive is a new modern animation platform that supports fancy user interactive vector animation. See project [Rive-Tizen](https://github.com/rive-app/rive-tizen) at [Github](https://github.com/rive-app/)
 203
 204 <p align="center">
 205   <img width="600" height="324" src="https://github.com/Samsung/thorvg/blob/master/res/example_rive.gif">
 206 </p>
 207
 208 [Back to contents](#contents)
 209 <br />
 210 <br />
 211 ## Examples
 212 There are various examples to understand ThorVG APIs, Please check sample code in `thorvg/src/examples`
 213
 214 To execute examples, you can build them with this meson option.
 215 ```
 216 meson -Dexamples=true . build
 217 ```
 218 Note that these examples are required EFL `elementary` package for launching. If you're using Linux-based OS, you could easily install its package from your OS distribution server. Otherwise, please visit the official [EFL page](https://enlightenment.org/) for more information.
 219
 220 [Back to contents](#contents)
 221 <br />
 222 <br />
 223 ## Tools
 224 ### ThorVG Viewer
 225 [ThorVG viewer](https://samsung.github.io/thorvg.viewer) supports immediate rendering through your browser. You can drag & drop SVG files on the page, see the rendering result on the spot.
 226
 227 [Back to contents](#contents)
 228 <br />
 229 <br />
 230 ### SVG to PNG
 231 ThorVG provides an executable `svg2png` converter which generate a PNG file from a SVG file.
 232
 233 To use `svg2png`, you must turn on its feature in the build option.
 234 ```
 235 meson -Dtools=svg2png . build
 236 ```
 237 Alternatively, you can add `svg2png` value to `tools` option in `meson_option.txt`. Build output will be located in `{builddir}/src/bin/svg2png/`
 238
 239 For more information, see `svg2png` usages:
 240 ```
 241 Usage:
 242    svg2png [svgFileName] [Resolution] [bgColor]
 243
 244 Examples:
 245     $ svg2png input.svg
 246     $ svg2png input.svg 200x200
 247     $ svg2png input.svg 200x200 ff00ff
 248 ```
 249 [Back to contents](#contents)
 250 <br />
 251 <br />
 252 ## API Bindings
 253 Our main development APIs are written in C++ but ThorVG also provides API bindings such as: C.
 254
 255 [Back to contents](#contents)
 256 <br />
 257 <br />
 258 ## Issues or Feature Requests?
 259 For immediate assistant or support please reach us in [Gitter](https://gitter.im/thorvg/community)