README.md

   1 [![License](https://img.shields.io/badge/licence-MIT-green.svg?style=flat)](LICENSE)
   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 <br>
   4 [![Build Linux](https://github.com/Samsung/thorvg/actions/workflows/actions.yml/badge.svg?branch=master&event=push)](https://github.com/Samsung/thorvg/actions/workflows/actions.yml)
   5 [![Build Windows](https://github.com/Samsung/thorvg/actions/workflows/build_win.yml/badge.svg?branch=master&event=push)](https://github.com/Samsung/thorvg/actions/workflows/build_win.yml)
   6
   7 # ThorVG
   8 <p align="center">
   9   <img width="800" height="400" src="https://github.com/Samsung/thorvg/blob/master/logo/512/thorvg-banner.png">
  10 </p>
  11 ThorVG is a platform-independent portable library for drawing vector-based scenes and animation. It's 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 a super compact size. It serves as the vector graphics engine for Tizen OS that powers many products. <br />
  12 <br />
  13 The following list shows primitives that are supported by ThorVG: <br />
  14  - Shapes: Line, Arc, Curve, Path, Polygon, ...
  15  - Filling: Solid, Linear and Radial Gradient
  16  - Scene Graph & Affine Transformation (translation, rotation, scale, ...)
  17  - Stroking: Width, Join, Cap, Dash
  18  - Composition: Blending, Masking, Path Clipping, ...
  19  - Pictures: TVG, SVG, JPG, PNG, Bitmap
  20 <p align="center">
  21   <img width="930" height="473" src="https://github.com/Samsung/thorvg/blob/master/res/example_primitives.png">
  22 </p>
  23 <br />
  24 If your program has the main renderer, your program could call ThorVG APIs while switching drawing contexts between the main renderer and ThorVG. During the API calls, ThorVG serializes drawing commands among the volatile paints' nodes then performs synchronous/asynchronous rendering using its backend raster engines. ThorVG supports vector images such as SVG, also expands, 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 />
  25 <br />
  26 <p align="center">
  27   <img width="900" height="288" src="https://github.com/Samsung/thorvg/blob/master/res/example_flow.png">
  28 </p>
  29 <br />
  30 ThorVG has the threading mechanism so that it tries to acquire the next scenes without delay. It runs its own fine-tuned task-scheduler built on threading pools, encapsulates all the jobs such as encoding, decoding, updating, rendering with tasks. As a result, all the tasks could run on multi-processing. The task scheduler is readied for hiding complexity, easier integration and user convenience. Thus the policy is optional, users can select it by their demands.<br />
  31 <br />
  32 <p align="center">
  33   <img width="900" height="313" src="https://github.com/Samsung/thorvg/blob/master/res/example_thread.png">
  34 </p>
  35 <br />
  36
  37 ## Contents
  38 - [Building ThorVG](#building-thorvg)
  39         - [Meson Build](#meson-build)
  40 - [Quick Start](#quick-start)
  41 - [SVG](#svg)
  42 - [TVG Picture](#tvg-picture)
  43 - [Practices](#practices)
  44         - [Tizen](#tizen)
  45         - [Rive](#rive)
  46         - [Godot](#godot)
  47 - [Examples](#examples)
  48 - [Documentation](#documentation)
  49 - [Tools](#tools)
  50         - [ThorVG Viewer](#thorvg-viewer)
  51         - [SVG to PNG](#svg-to-png)
  52         - [SVG to TVG](#svg-to-tvg)
  53 - [API Bindings](#api-bindings)
  54 - [Dependencies](#dependencies)
  55 - [Issues or Feature Requests](#issues-or-feature-requests)
  56
  57 [](#contents)
  58 <br />
  59 ## Building ThorVG
  60 ThorVG supports [meson](https://mesonbuild.com/) build system.
  61 <br />
  62 ### Meson Build
  63 Install [meson](http://mesonbuild.com/Getting-meson.html) and [ninja](https://ninja-build.org/) if not already installed.
  64
  65 Run meson to configure ThorVG:
  66 ```
  67 meson build
  68 ```
  69 Run ninja to build & install ThorVG:
  70 ```
  71 ninja -C build install
  72 ```
  73 [Back to contents](#contents)
  74 <br />
  75 <br />
  76 ## Quick Start
  77 ThorVG renders vector shapes to a given canvas buffer. The following is a quick start to show you how to use the essential APIs.
  78
  79 First, you should initialize the ThorVG engine:
  80
  81 ```cpp
  82 tvg::Initializer::init(tvg::CanvasEngine::Sw, 0);   //engine method, thread count
  83 ```
  84
  85 Then it would be best if you prepared an empty canvas for drawing on it:
  86
  87 ```cpp
  88 static uint32_t buffer[WIDTH * HEIGHT];                                 //canvas target buffer
  89
  90 auto canvas = tvg::SwCanvas::gen();                                     //generate a canvas
  91 canvas->target(buffer, WIDTH, WIDTH, HEIGHT, tvg::SwCanvas::ARGB8888);  //buffer, stride, w, h, Colorspace
  92 ```
  93
  94 Next you can draw multiple shapes on the canvas:
  95
  96 ```cpp
  97 auto rect = tvg::Shape::gen();               //generate a shape
  98 rect->appendRect(50, 50, 200, 200, 20, 20);  //define it as a rounded rectangle (x, y, w, h, rx, ry)
  99 rect->fill(100, 100, 100, 255);              //set its color (r, g, b, a)
 100 canvas->push(move(rect));                    //push the rectangle into the canvas
 101
 102 auto circle = tvg::Shape::gen();             //generate a shape
 103 circle->appendCircle(400, 400, 100, 100);    //define it as a circle (cx, cy, rx, ry)
 104
 105 auto fill = tvg::RadialGradient::gen();      //generate a radial gradient
 106 fill->radial(400, 400, 150);                 //set the radial gradient geometry info (cx, cy, radius)
 107
 108 tvg::Fill::ColorStop colorStops[2];          //gradient colors
 109 colorStops[0] = {0.0, 255, 255, 255, 255};   //1st color values (offset, r, g, b, a)
 110 colorStops[1] = {1.0, 0, 0, 0, 255};         //2nd color values (offset, r, g, b, a)
 111 fill->colorStops(colorStops, 2);             //set the gradient colors info
 112
 113 circle->fill(move(fill));                    //set the circle fill
 114 canvas->push(move(circle));                  //push the circle into the canvas
 115
 116 ```
 117
 118 This code generates the following result:
 119
 120 <p align="center">
 121   <img width="416" height="411" src="https://github.com/Samsung/thorvg/blob/master/res/example_shapes.png">
 122 </p>
 123
 124 You can also draw you own shapes and use dashed stroking:
 125
 126 ```cpp
 127 auto path = tvg::Shape::gen();               //generate a path
 128 path->moveTo(199, 34);                       //set sequential path coordinates
 129 path->lineTo(253, 143);
 130 path->lineTo(374, 160);
 131 path->lineTo(287, 244);
 132 path->lineTo(307, 365);
 133 path->lineTo(199, 309);
 134 path->lineTo(97, 365);
 135 path->lineTo(112, 245);
 136 path->lineTo(26, 161);
 137 path->lineTo(146, 143);
 138 path->close();
 139
 140 path->fill(150, 150, 255, 255);              //path color
 141
 142 path->stroke(3);                             //stroke width
 143 path->stroke(0, 0, 255, 255);                //stroke color
 144 path->stroke(tvg::StrokeJoin::Round);        //stroke join style
 145 path->stroke(tvg::StrokeCap::Round);         //stroke cap style
 146
 147 float pattern[2] = {10, 10};                 //stroke dash pattern (line, gap)
 148 path->stroke(pattern, 2);                    //set the stroke pattern
 149
 150 canvas->push(move(path));                    //push the path into the canvas
 151
 152 ```
 153
 154 The code generates the following result:
 155
 156 <p align="center">
 157   <img width="300" height="300" src="https://github.com/Samsung/thorvg/blob/master/res/example_path.png">
 158 </p>
 159
 160 Now begin rendering & finish it at a particular time:
 161
 162 ```cpp
 163 canvas->draw();
 164 canvas->sync();
 165 ```
 166
 167 Then you can acquire the rendered image from the buffer memory.
 168
 169 Lastly, terminate the engine after its usage:
 170
 171 ```cpp
 172 tvg::Initializer::term(tvg::CanvasEngine::Sw);
 173 ```
 174 [Back to contents](#contents)
 175 <br />
 176 <br />
 177 ## SVG
 178
 179 ThorVG supports SVG (Scalable Vector Graphics) rendering through its SVG interpreter. It satisfies the [SVG Tiny Specification](https://www.w3.org/TR/SVGTiny12/)
 180 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:
 181
 182  - Animation
 183  - Fonts & Text
 184  - Interactivity
 185  - Multimedia
 186  - Scripting (Partially Supported)
 187
 188 The following code snippet shows how to draw SVG image using ThorVG:
 189
 190 ```cpp
 191 auto picture = tvg::Picture::gen();         //generate a picture
 192 picture->load("tiger.svg");                 //load SVG file
 193 canvas->push(move(picture));                //push the picture into the canvas
 194 ```
 195
 196 The result:
 197
 198 <p align="center">
 199   <img width="300" height="300" src="https://github.com/Samsung/thorvg/blob/master/res/example_tiger.png">
 200 </p>
 201
 202 [Back to contents](#contents)
 203 <br />
 204 <br />
 205 ## TVG Picture
 206
 207 ThorVG provides the designated vector data format which is called TVG Picture. TVG Picture stores a list of properties of the Paint nodes of a scene in binary form. The data saved in a TVG Picture is optimized beforehand, keeping the resulting file small and the data loading process fast and efficient.
 208
 209 To save data in a TVG Picture format, ThorVG uses a dedicated module - TVG Saver. It is responsible for optimizing the data of all the scene-tree nodes and saving them in binary format. In the optimization process, the TVG Saver filters out unused information, removing the duplicated properties, merges the overlapping shapes and compresses the data if possible, but keeping the TVG Pictures compatible with the later version of ThorVG libraries. In case of compression, it uses [Lempel-Ziv-Welchi](https://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Welch) data compression algorithm.
 210
 211 The final data size is smaller in comparison to any other text-based vector data format, such as SVG, which in turn decreases the required application resources. This helps not only reduce the number of I/O operations but also reduces the memory bandwidth while loading the data. Thus this is effective if your program uses a big amount of the vector resources.
 212
 213 Additionally, TVG Picture helps to reduce the resource loading tasks since it can skip interpreting the data stage. That brings the reduced amount of the required runtime memory and rendering tasks that increases the performance.
 214
 215 Utilizing the TVG Picture allows you to reduce the data size and loading time by more than 30%, on average ([See More](https://github.com/Samsung/thorvg/wiki/TVG-Picture-Binary-Size)). Note that the charge in the performance rate depends on the resource size and its complexity.
 216
 217 <p align="center">
 218   <img width="909" height="314" src="https://github.com/Samsung/thorvg/blob/master/res/example_tvgsize.png">
 219 </p>
 220
 221 While TVG Saver exports the scene-tree to the TVG Picture data files(TVG), the TVG Loader imports and restores it to the programmable instances. You can quickly use the ThorVG Viewer to convert files from SVG to TVG.
 222
 223 <p align="center">
 224   <img width="710" height="215" src="https://github.com/Samsung/thorvg/blob/master/res/example_tvgmodule.png">
 225 </p>
 226
 227
 228 [Back to contents](#contents)
 229 <br />
 230 <br />
 231 ## Practices
 232 ### Tizen
 233 ThorVG is integrated into the [Tizen](https://www.tizen.org) platform as the vector graphics engine. It's being used for vector primitive drawings
 234 and scalable image contents such as SVG and Lottie Animation among the Tizen powered products.
 235
 236 <p align="center">
 237   <img width="798" height="285" src="https://github.com/Samsung/thorvg/blob/master/res/example_tizen.png">
 238 </p>
 239
 240 [Back to contents](#contents)
 241 <br />
 242 <br />
 243 ### Rive
 244 We're also building a [Rive](https://rive.app/) port that supports Rive Animation run through the ThorVG backend. Rive is a brand new animation platform
 245 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/).
 246
 247 <p align="center">
 248   <img width="600" height="324" src="https://github.com/Samsung/thorvg/blob/master/res/example_rive.gif">
 249 </p>
 250
 251 [Back to contents](#contents)
 252 <br />
 253 <br />
 254 ### Godot
 255 ThorVG has been integrated into the [Godot](https://www.godotengine.org) project for use of neat and slick icons in Godot editors. Godot is a completely free and open-source modern game engine, it provides a huge set of common tools, so you can just focus on making your game without reinventing the wheel.
 256
 257 <p align="center">
 258   <img width="798" height="461" src="https://github.com/Samsung/thorvg/blob/master/res/example_godot.png">
 259 </p>
 260
 261 [Back to contents](#contents)
 262 <br />
 263 <br />
 264 ## Examples
 265 There are various examples available in `thorvg/src/examples` to help you understand ThorVG APIs.
 266
 267 To execute these examples, you can build them with the following meson option:
 268 ```
 269 meson -Dexamples=true . build
 270 ```
 271 Note that these examples require the EFL `elementary` package for launching. If you're using Linux-based OS, you can easily
 272 install this package from your OS distribution server. Otherwise, please visit the official [EFL page](https://enlightenment.org/) for more information.
 273
 274 [Back to contents](#contents)
 275 <br />
 276 <br />
 277 ## Documentation
 278 ThorVG API documentation is available at [thorvg.org/apis](https://www.thorvg.org/apis), and can also found in the [docs](/docs) folder of this repo.
 279
 280 [Back to contents](#contents)
 281 <br />
 282 <br />
 283 ## Tools
 284 ### ThorVG Viewer
 285 ThorVG provides the resource verification tool for the ThorVG Engine. [ThorVG viewer](https://samsung.github.io/thorvg.viewer) does immediate rendering via web browser running on the ThorVG web-assembly binary, allowing real-time editing of the vector elements on it. It doesn't upload your resources to any external server while allowing to export to supported formats such as TVG, so the designer resource copyright is protected.
 286
 287 https://user-images.githubusercontent.com/71131832/130445967-fb8f7d81-9c89-4598-b7e4-2c046d5d7438.mp4
 288
 289
 290 [Back to contents](#contents)
 291 <br />
 292 <br />
 293 ### SVG to PNG
 294 ThorVG provides an executable `svg2png` converter that generates a PNG file from an SVG file.
 295
 296 To use the `svg2png`, you must turn on this feature in the build option:
 297 ```
 298 meson -Dtools=svg2png . build
 299 ```
 300 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/`.
 301 <br />
 302
 303 To use the `svg2png` converter you have to pass the `SVG files` parameter. It can be a file name with the `.svg` extension or a directory name. Multiple files or directories separated by a space are also accepted. If a directory is passed, the `.svg` file extension is searched inside it and in all of its subdirectories.
 304
 305 Optionally, the image resolution can be provided in the `WxH` format (two numbers separated by an `x` sign) following the `-r` flag.
 306 <br />
 307 The background color can be set with the `-b` flag. The `bgColor` parameter should be passed as a three-bytes hexadecimal value in the `ffffff` format. The default background is transparent.
 308 <br />
 309 Both flags, if provided, are applied to all of the `.svg` files.
 310
 311 The usage examples of the `svg2png`:
 312 ```
 313 Usage:
 314     svg2png [SVG files] [-r resolution] [-b bgColor]
 315
 316 Flags:
 317     -r set the output image resolution.
 318     -b set the output image background color.
 319
 320 Examples:
 321     $ svg2png input.svg
 322     $ svg2png input.svg -r 200x200
 323     $ svg2png input.svg -r 200x200 -b ff00ff
 324     $ svg2png input1.svg input2.svg -r 200x200 -b ff00ff
 325     $ svg2png . -r 200x200
 326 ```
 327 [Back to contents](#contents)
 328 <br />
 329 <br />
 330 ### SVG to TVG
 331 ThorVG provides an executable `svg2tvg` converter that generates a TVG file from an SVG file.
 332
 333 To use `svg2tvg`, you must turn on this feature in the build option:
 334 ```
 335 meson -Dtools=svg2tvg . build
 336 ```
 337 Alternatively, you can add the `svg2tvg` value to the `tools` option in `meson_option.txt`. The build output will be located in `{builddir}/src/bin/svg2tvg/`.
 338
 339 Examples of the usage of the `svg2tvg`:
 340 ```
 341 Usage:
 342    svg2tvg [SVG file] or [SVG folder]
 343
 344 Examples:
 345     $ svg2tvg input.svg
 346     $ svg2tvg svgfolder
 347 ```
 348 [Back to contents](#contents)
 349 <br />
 350 <br />
 351 ## API Bindings
 352 Our main development APIs are written in C++, but ThorVG also provides API bindings for C.
 353
 354 [Back to contents](#contents)
 355 <br />
 356 <br />
 357 ## Dependencies
 358 The ThorVG core has no dependencies. However, ThorVG has optional feature extensions. Some of these have dependencies as follows:
 359
 360 * GL renderer: EGL, GLESv2
 361 * PNG support: [libpng](https://github.com/glennrp/libpng)
 362 * JPG support: [turbojpeg](https://github.com/libjpeg-turbo/libjpeg-turbo)
 363 * Examples: [EFL](https://www.enlightenment.org/about-efl.md)
 364
 365 [Back to contents](#contents)
 366 <br />
 367 <br />
 368 ## Issues or Feature Requests
 369 For support, please reach us in [Gitter](https://gitter.im/thorvg/community).