README.md

   1 [![Build Status](https://travis-ci.org/Samsung/thorvg.svg?branch=master)](https://travis-ci.org/Samsung/thorvg)
   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  - Paints: Line, Arc, Curve, Path, Shapes, Polygons
  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, Bitmap, ...
  19 <p align="center">
  20   <img width="930" height="212" 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 - [Examples](#examples)
  35 - [Tools](#tools)
  36         - [ThorVG Viewer](#thorvg-viewer)
  37         - [SVG to PNG](#svg-to-png)
  38 - [API Bindings](#api-bindings)
  39 - [Issues or Feature Requests?](#issues-or-feature-requests)
  40
  41 [](#contents)
  42 <br />
  43 ## Building ThorVG
  44 Basically, ThorVG supports [meson](https://mesonbuild.com/) build system.
  45 <br />
  46 ### Meson Build
  47 Install [meson](http://mesonbuild.com/Getting-meson.html) and [ninja](https://ninja-build.org/) if not already installed.
  48
  49 Run meson to configure ThorVG.
  50 ```
  51 meson build
  52 ```
  53 Run ninja to build & install ThorVG.
  54 ```
  55 ninja -C build install
  56 ```
  57 [Back to contents](#contents)
  58 <br />
  59 <br />
  60 ## Quick Start
  61 ThorVG renders vector shapes on a given canvas buffer. Here shows quick start to learn basic API usages.
  62
  63 First, You can initialize ThorVG engine.
  64
  65 ```cpp
  66 tvg::Initializer::init(tvg::CanvasEngine::Sw, 0);   //engine method, thread count
  67 ```
  68
  69 You can prepare a empty canvas for drawing on it.
  70
  71 ```cpp
  72 static uint32_t buffer[WIDTH * HEIGHT];          //canvas target buffer
  73
  74 auto canvas = tvg::SwCanvas::gen();              //generate a canvas
  75 canvas->target(buffer, WIDTH, WIDTH, HEIGHT);    //stride, w, h
  76 ```
  77
  78 Next you can draw multiple shapes onto the canvas.
  79
  80 ```cpp
  81 auto rect = tvg::Shape::gen();               //generate a round rectangle
  82 rect->appendRect(50, 50, 200, 200, 20, 20);  //round geometry(x, y, w, h, rx, ry)
  83 rect->fill(100, 100, 0, 255);                //round rectangle color (r, g, b, a)
  84 canvas->push(move(rect));                    //push round rectangle drawing command
  85
  86 auto circle = tvg::Shape::gen();             //generate a circle
  87 circle->appendCircle(400, 400, 100, 100);    //circle geometry(cx, cy, radiusW, radiusH)
  88
  89 auto fill = tvg::RadialGradient::gen();      //generate radial gradient for circle fill
  90 fill->radial(400, 400, 150);                 //radial fill info(cx, cy, radius)
  91
  92 tvg::Fill::ColorStop colorStops[2];          //gradient color info
  93 colorStops[0] = {0, 255, 255, 255, 255};     //index, r, g, b, a (1st color value)
  94 colorStops[1] = {1, 0, 0, 0, 255};           //index, r, g, b, a (2nd color value)
  95 fill.colorStops(colorStop, 2);               //set fil with gradient color info
  96
  97 circle->fill(move(fill));                    //circle color
  98 canvas->push(move(circle));                  //push circle drawing command
  99
 100 ```
 101
 102 This code result looks like this.
 103
 104 <p align="center">
 105   <img width="416" height="411" src="https://github.com/Samsung/thorvg/blob/master/res/example_shapes.png">
 106 </p>
 107
 108 Or you can draw pathes with dash stroking.
 109
 110 ```cpp
 111 auto path = tvg::Shape::gen();               //generate a path
 112 path->moveTo(199, 34);                       //set sequential path coordinates
 113 path->lineTo(253, 143);
 114 path->lineTo(374, 160);
 115 path->lineTo(287, 244);
 116 path->lineTo(307, 365);
 117 path->lineTo(199, 309);
 118 path->lineTo(97, 365);
 119 path->lineTo(112, 245);
 120 path->lineTo(26, 161);
 121 path->lineTo(146, 143);
 122 path->close();
 123
 124 path->fill(150, 150, 255, 255);              //path color
 125
 126 path->stroke(3);                             //stroke width
 127 path->stroke(0, 0, 255, 255);                //stroke color
 128 path->stroke(tvg::StrokeJoin::Round);        //stroke join style
 129 path->stroke(tvg::StrokeCap::Round);         //stroke cap style
 130
 131 float pattern[2] = {10, 10};
 132 path->stroke(pattern, 2);                    //stroke dash pattern (line, gap)
 133
 134 canvas->push(move(path));                    //push path drawing command
 135
 136 ```
 137
 138 This path drawing result shows like this.
 139
 140 <p align="center">
 141   <img width="300" height="300" src="https://github.com/Samsung/thorvg/blob/master/res/example_path.png">
 142 </p>
 143
 144 Next, this code snippet shows you how to draw SVG image.
 145
 146 ```cpp
 147 auto picture = tvg::Picture::gen();         //generate a picture
 148 picture->load("tiger.svg");                 //Load SVG file.
 149 canvas->push(move(picture));                //push picture drawing command
 150 ```
 151
 152 And here is the result.
 153
 154 <p align="center">
 155   <img width="300" height="300" src="https://github.com/Samsung/thorvg/blob/master/res/example_tiger.png">
 156 </p>
 157
 158 Begin rendering & finish it at a particular time.
 159
 160 ```cpp
 161 canvas->draw();
 162 canvas->sync();
 163 ```
 164
 165 Now you can acquire the rendered image from the buffer memory.
 166
 167 Lastly, terminate the engine after usage.
 168
 169 ```cpp
 170 tvg::Initializer::term(tvg::CanvasEngine::Sw);
 171 ```
 172 [Back to contents](#contents)
 173 <br />
 174 <br />
 175 ## Examples
 176 There are various examples to understand ThorVG APIs, Please check sample code in `thorvg/src/examples`
 177
 178 To execute examples, you can build them with this meson option.
 179 ```
 180 meson -Dexamples=true . build
 181 ```
 182 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.
 183
 184 [Back to contents](#contents)
 185 <br />
 186 <br />
 187 ## Tools
 188 ### ThorVG Viewer
 189 [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.
 190
 191 [Back to contents](#contents)
 192 <br />
 193 <br />
 194 ### SVG to PNG
 195 ThorVG provides an executable `svg2png` converter which generate a PNG file from a SVG file.
 196
 197 To use `svg2png`, you must turn on its feature in the build option.
 198 ```
 199 meson -Dtools=svg2png . build
 200 ```
 201 Alternatively, you can add `svg2png` value to `tools` option in `meson_option.txt`. Build output will be located in `{builddir}/src/bin/svg2png/`
 202
 203 For more information, see `svg2png` usages:
 204 ```
 205 Usage:
 206    svg2png [svgFileName] [Resolution] [bgColor]
 207
 208 Examples:
 209     $ svg2png input.svg
 210     $ svg2png input.svg 200x200
 211     $ svg2png input.svg 200x200 ff00ff
 212 ```
 213 [Back to contents](#contents)
 214 <br />
 215 <br />
 216 ## API Bindings
 217 Our main development APIs are written in C++ but ThorVG also provides API bindings such as: C.
 218
 219 [Back to contents](#contents)
 220 <br />
 221 <br />
 222 ## Issues or Feature Requests?
 223 For immediate assistant or support please reach us in [Gitter](https://gitter.im/thorvg/community)