inc/thorvg_capi.h

   1 /*!
   2 * \file thorvg_capi.h
   3 * \brief Function provides C bindings for thorvg library.
   4 * Please refer to src/examples/Capi.cpp to find thorvg_capi examples.
   5 *
   6 * thorvg_capi module provides a set of functionality that allows to
   7 * implement thorvg C client with following funcionalities
   8 * - Drawing primitive paints: Line, Arc, Curve, Path, Shapes, Polygons
   9 * - Filling: Solid, Linear, Radial Gradient
  10 * - Scene Graph & Affine Transformation (translation, rotation, scale ...)
  11 * - Stroking: Width, Join, Cap, Dash
  12 * - Composition: Blending, Masking, Path Clipping, etc
  13 * - Pictures: SVG, Bitmap
  14 */
  15
  16 #ifndef __THORVG_CAPI_H__
  17 #define __THORVG_CAPI_H__
  18
  19 /*! Importation of librairies*/
  20 #include <stdbool.h>
  21
  22 #ifdef TVG_EXPORT
  23     #undef TVG_EXPORT
  24 #endif
  25
  26 #ifdef TVG_BUILD
  27     #define TVG_EXPORT __attribute__ ((visibility ("default")))
  28 #else
  29     #define TVG_EXPORT
  30 #endif
  31
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 typedef struct _Tvg_Canvas Tvg_Canvas;
  38 typedef struct _Tvg_Paint Tvg_Paint;
  39 typedef struct _Tvg_Gradient Tvg_Gradient;
  40
  41 /**
  42 * \defgroup ThorVGCapi C APIs
  43 * \brief ThorVG provides C interface.
  44 *
  45 * \{
  46 */
  47
  48 /**
  49 * \defgroup ThorVGCapi_Initializer Initializer
  50 * \brief Enables initialization and termination of the ThorVG engine.
  51 *
  52 * \{
  53 */
  54
  55 /*!
  56 * \def TVG_ENGINE_SW
  57 * Software raster engine type.
  58 */
  59 #define TVG_ENGINE_SW (1 << 1)
  60
  61
  62 /*!
  63 * \def TVG_ENGINE_GL
  64 * GL raster engine type.
  65 */
  66 #define TVG_ENGINE_GL (1 << 2)
  67
  68 /*\}*/
  69
  70 /*!
  71 * \ingroup ThorVGCapi_Canvas
  72 * \def TVG_COLORSPACE_ABGR8888
  73 * Colorspace used to fill buffer.
  74 */
  75 #define TVG_COLORSPACE_ABGR8888 0
  76
  77
  78 /*!
  79 * \ingroup ThorVGCapi_Canvas
  80 * \def TVG_COLORSPACE_ARGB8888
  81 * Colorspace used to fill buffer.
  82 */
  83 #define TVG_COLORSPACE_ARGB8888 1
  84
  85
  86 typedef enum {
  87     TVG_RESULT_SUCCESS = 0,
  88     TVG_RESULT_INVALID_ARGUMENT,
  89     TVG_RESULT_INSUFFICIENT_CONDITION,
  90     TVG_RESULT_FAILED_ALLOCATION,
  91     TVG_RESULT_MEMORY_CORRUPTION,
  92     TVG_RESULT_NOT_SUPPORTED,
  93     TVG_RESULT_UNKNOWN
  94 } Tvg_Result;
  95
  96
  97 typedef enum {
  98     TVG_PATH_COMMAND_CLOSE = 0,
  99     TVG_PATH_COMMAND_MOVE_TO,
 100     TVG_PATH_COMMAND_LINE_TO,
 101     TVG_PATH_COMMAND_CUBIC_TO
 102 } Tvg_Path_Command;
 103
 104
 105 typedef enum {
 106     TVG_STROKE_CAP_SQUARE = 0,
 107     TVG_STROKE_CAP_ROUND,
 108     TVG_STROKE_CAP_BUTT
 109 } Tvg_Stroke_Cap;
 110
 111
 112 typedef enum {
 113     TVG_STROKE_JOIN_BEVEL = 0,
 114     TVG_STROKE_JOIN_ROUND,
 115     TVG_STROKE_JOIN_MITER
 116 } Tvg_Stroke_Join;
 117
 118
 119 typedef enum {
 120     TVG_STROKE_FILL_PAD = 0,
 121     TVG_STROKE_FILL_REFLECT,
 122     TVG_STROKE_FILL_REPEAT
 123 } Tvg_Stroke_Fill;
 124
 125
 126 typedef enum {
 127     TVG_FILL_RULE_WINDING = 0,
 128     TVG_FILL_RULE_EVEN_ODD
 129 } Tvg_Fill_Rule;
 130
 131
 132 typedef enum {
 133     TVG_COMPOSITE_METHOD_NONE = 0,
 134     TVG_COMPOSITE_METHOD_CLIP_PATH,
 135     TVG_COMPOSITE_METHOD_ALPHA_MASK,
 136     TVG_COMPOSITE_METHOD_INVERSE_ALPHA_MASK,
 137 } Tvg_Composite_Method;
 138
 139
 140 typedef struct
 141 {
 142     float x, y;
 143 } Tvg_Point;
 144
 145
 146 typedef struct
 147 {
 148     float e11, e12, e13;
 149     float e21, e22, e23;
 150     float e31, e32, e33;
 151 } Tvg_Matrix;
 152
 153
 154 typedef struct
 155 {
 156     float offset;
 157     uint8_t r, g, b, a;
 158 } Tvg_Color_Stop;
 159
 160
 161 /************************************************************************/
 162 /* Engine API                                                           */
 163 /************************************************************************/
 164 /*!
 165 * \fn Tvg_Result tvg_engine_init(unsigned engine_method, unsigned threads)
 166 * \brief The funciton initialises thorvg library. It must be called before the
 167 * other functions at the beggining of thorvg client.
 168 * \ingroup ThorVGCapi_Initializer Initializer
 169 * \code
 170 * tvg_engine_init(TVG_ENGINE_SW, 0); //Initialize software renderer and use 1 thread
 171 * \endcode
 172 * \param[in] engine_method renderer type
 173 *   - TVG_ENGINE_SW: software renderer
 174 *   - TVG_ENGINE_GL: opengl renderer (not supported yet)
 175 * \param[in] threads number of threads used to perform rendering. If threads = 0, only one
 176 * thread will be used for renderer
 177 * \return Tvg_Result return values:
 178 *   - TVG_RESULT_SUCCESS: if ok.
 179 *   - TVG_RESULT_INSUFFICENT_CONDITION: multiple init calls.
 180 *   - TVG_RESULT_INVALID_ARGUMENT: not known engine_method.
 181 *   - TVG_RESULT_NOT_SUPPORTED: not supported engine_method.
 182 *   - TVG_RESULT_UNKOWN: internal error.
 183 */
 184 TVG_EXPORT Tvg_Result tvg_engine_init(unsigned engine_method, unsigned threads);
 185
 186
 187 /*!
 188 * \fn TVG_EXPORT Tvg_Result tvg_engine_term(unsigned engine_method)
 189 * \brief The funciton termiates renderer tasks. Used for cleanup.
 190 * It should be called in case of termination of the thorvg library with same
 191 * renderer types as it was passed in tvg_engine_init()
 192 * \ingroup ThorVGCapi_Initializer Initializer
 193 * \code
 194 * tvg_engine_init(TVG_ENGINE_SW, 0);
 195 * //define canvas and shapes, update shapes, general rendering calls
 196 * tvg_engine_term(TVG_ENGINE_SW);
 197 * \endcode
 198 * \param engine_method renderer type
 199 *   - TVG_ENGINE_SW: software renderer
 200 *   - TVG_ENGINE_GL: opengl renderer (not supported yet)
 201 * \return Tvg_Result return values:
 202 *   - TVG_RESULT_SUCCESS: if ok.
 203 *   - TVG_RESULT_INSUFFICENT_CONDITION: multiple terminate calls.
 204 *   - TVG_RESULT_INVALID_ARGUMENT: not known engine_method.
 205 *   - TVG_RESULT_NOT_SUPPORTED: not supported engine_method.
 206 *   - TVG_RESULT_UNKOWN: internal error.
 207 */
 208 TVG_EXPORT Tvg_Result tvg_engine_term(unsigned engine_method);
 209
 210
 211 /**
 212 * \defgroup ThorVGCapi_Canvas Canvas
 213 * \brief Functions for drawing graphic elements.
 214 * It stores all Paint objects (Shape, Scene, Picture) and creates the buffer, which can be drawn on the screen.
 215 *
 216 * \{
 217 */
 218
 219 /**
 220 * \defgroup ThorVGCapi_SwCanvas SwCanvas
 221 * \ingroup ThorVGCapi_Canvas
 222 * \brief Functions for the rasterisation of graphic elements with a software engine.
 223 *
 224 * \{
 225 */
 226
 227 /************************************************************************/
 228 /* SwCanvas API                                                         */
 229 /************************************************************************/
 230 /*!
 231 * \fn TVG_EXPORT Tvg_Canvas* tvg_swcanvas_create()
 232 * \brief The function creates a canvas, i.e. an object used for drawing shapes,
 233 * scenes (Tvg_Paint objects)
 234 * \code
 235 * Tvg_Canvas *canvas = NULL;
 236 *
 237 * tvg_engine_init(TVG_ENGINE_SW, 4);
 238 * canvas = tvg_swcavnas_create();
 239 *
 240 * //setup canvas buffer
 241 * uint32_t *buffer = NULL;
 242 * buffer = (uint32_t*) malloc(sizeof(uint32_t) * 100 * 100);
 243 * if (!buffer) return;
 244 *
 245 * tvg_swcanvas_set_target(canvas, buffer, 100, 100, 100, TVG_COLORSPACE_ARGB8888);
 246 *
 247 * //add paints to canvas and setup them before draw calls
 248 *
 249 * tvg_canvas_destroy(canvas);
 250 * tvg_engine_term(TVG_ENGINE_SW);
 251 * \endcode
 252 * \return Tvg_Canvas pointer to the canvas object, or NULL if something went wrong
 253 */
 254
 255
 256 TVG_EXPORT Tvg_Canvas* tvg_swcanvas_create();
 257 /*!
 258 * \fn TVG_EXPORT Tvg_Result tvg_swcanvas_set_target(Tvg_Canvas* canvas, uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h, uint32_t cs)
 259 * \brief The function sets memory buffer used by renderer and define colorspace used for renderering. For optimisation reasons, the library
 260 * does not allocate memory for the output buffer on its own. Buffer is used to integrate thorvg with external libraries. Please refer to examples/Capi.cpp
 261 * where thorvg is integrated with the EFL lib.
 262 * \param[in] canvas The pointer to Tvg_Canvas object.
 263 * \param[in] buffer The uint32_t pointer to allocated memory.
 264 * \param[in] stride The buffer stride - in most cases width.
 265 * \param[in] w The buffer width
 266 * \param[in] h The buffer height
 267 * \param[in] cs The buffer colorspace, defines position of color in raw pixel data.
 268 * - TVG_COLORSPACE_ABGR8888
 269 * - TVG_COLORSPACE_ARGB8888
 270 * \return Tvg_Result return values:
 271 * - TVG_RESULT_SUCCESS: if ok.
 272 * - TVG_RESULT_MEMORY_CORRUPTION: A canvas is not valid.
 273 * - TVG_RESULT_INVALID_ARGUMENTS: invalid buffer, stride = 0, w or h = 0
 274 */
 275 TVG_EXPORT Tvg_Result tvg_swcanvas_set_target(Tvg_Canvas* canvas, uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h, uint32_t cs);
 276
 277
 278 /* \} */
 279
 280
 281 /************************************************************************/
 282 /* Common Canvas API                                                    */
 283 /************************************************************************/
 284 /*!
 285 * \fn TVG_EXPORT Tvg_Result tvg_canvas_destroy(Tvg_Canvas* canvas)
 286 * \brief The function clears canvas internal data (e.g all paints stored by canvas)
 287 * and destroy canvas object. There is no need to call tvg_paint_del API manually for
 288 * each paint. This function releases stored paints data. If there is a need to destroy
 289 * paint manually in thorvg client runtime tvg_canvas_clear(canvas, false) API should be
 290 * called, but in that case all shapes should be deleted by thorvg client.
 291 * \code
 292 * static Tvg_Canvas *canvas = NULL;
 293 * static uint32_t *buffer = NULL;
 294 *
 295 * static void _init() {
 296 *   canvas = tvg_swcavnas_create();
 297 *   buffer = (uint32_t*) malloc(sizeof(uint32_t) * 100 * 100);
 298 *   tvg_swcanvas_set_target(canvas, buffer, 100, 100, 100, TVG_COLORSPACE_ARGB8888);
 299 * }
 300 *
 301 * //a task called from main function in a loop
 302 * static void _job(const int cmd) {
 303 *   switch (cmd) {
 304 *     case CMD_EXIT: return 0;
 305 *     case CMD_ADD_RECT:
 306 *       //define valid rectangle shape
 307 *       tvg_canvas_push(canvas, rect);
 308 *       break;
 309 *     case CMD_DEL_RECT:
 310 *       tvg_shape_del(rect);
 311 *       //now to safely delete Tvg_Canvas, tvg_canvas_clear() API have to be used.
 312 *       break;
 313 *     default:
 314 *       break;
 315 *   }
 316 * }
 317 *
 318 * int main(int argc, char **argv) {
 319 *   int cmd = 0;
 320 *   int stop = 1;
 321 *
 322 *   tvg_engine_init(TVG_ENGINE_SW, 4);
 323 *
 324 *   while (stop) {
 325 *      //wait for command e.g. from console
 326 *      stop = _job(cmd);
 327 *   }
 328 *   tvg_canvas_clear(canvas, false);
 329 *   tvg_canvas_destroy(canvas);
 330 *   tvg_engine_term(TVG_ENGINE_SW);
 331 *   return 0;
 332 * }
 333 *
 334 *
 335 * tvg_canvas_destroy(canvas);
 336 * tvg_engine_term()
 337 * \endcode
 338 * \param[in] canvas Tvg_Canvas pointer
 339 * \return Tvg_Result return values:
 340 * - TVG_RESULT_SUCCESS: if ok.
 341 * - TVG_RESULT_INVALID_ARGUMENT: if canvas is a NULL pointer.
 342 */
 343 TVG_EXPORT Tvg_Result tvg_canvas_destroy(Tvg_Canvas* canvas);
 344
 345
 346 /*!
 347 * \fn TVG_EXPORT Tvg_Result tvg_canvas_push(Tvg_Canvas* canvas, Tvg_Paint* paint)
 348 * \brief The function inserts paint object in the canvas.
 349 * \param[in] canvas Tvg_Canvas pointer
 350 * \param[in] paint Tvg_Paint pointer
 351 * \return Tvg_Result return values:
 352 * - TVG_RESULT_SUCCESS: if ok.
 353 * - TVG_RESULT_INVALID_PARAMETERS: if canvas or if paint are NULL pointers.
 354 * - TVG_RESULT_MEMORY_CORRUPTION: if paint is not a valid Tvg_Paint object.
 355 */
 356 TVG_EXPORT Tvg_Result tvg_canvas_push(Tvg_Canvas* canvas, Tvg_Paint* paint);
 357
 358
 359 /*!
 360 * \fn TVG_EXPORT Tvg_Result tvg_canvas_reserve(Tvg_Canvas* canvas, uint32_t n)
 361 * \brief The function reserves a memory for objects. It might be used to reduce
 362 * reallocations in any cases when number of Tvg_Paints stored in canvas is known
 363 * or it can be estimated.
 364 * \code
 365 * Tvg_Canvas *canvas = NULL;
 366 *
 367 * tvg_engine_init(TVG_ENGINE_SW, 4);
 368 * canvas = tvg_swcavnas_create();
 369 *
 370 * uint32_t *buffer = NULL;
 371 * buffer = (uint32_t*) malloc(sizeof(uint32_t) * 100 * 100);
 372 * if (!buffer) return;
 373 *
 374 * tvg_swcanvas_set_target(canvas, buffer, 100, 100, 100, TVG_COLORSPACE_ARGB8888);
 375 * tvg_canvas_reserve(canvas, 100); //reserve array for 100 paints in canvas.
 376 *
 377 * tvg_canvas_destroy(canvas);
 378 * tvg_engine_term()
 379 * \endcode
 380 * \param[in] canvas Tvg_Canvas pointer.
 381 * \param[in] n uint32_t reserved space.
 382 * \return Tvg_Result return values:
 383 * - TVG_RESULT_SUCCESS: if ok.
 384 * - TVG_RESULT_INVALID_PARAMETERS: if canvas is invalid.
 385 */
 386 TVG_EXPORT Tvg_Result tvg_canvas_reserve(Tvg_Canvas* canvas, uint32_t n);
 387
 388
 389 /*!
 390 * \fn TVG_EXPORT Tvg_Result tvg_canvas_clear(Tvg_Canvas* canvas, bool free)
 391 * \brief The function clears a Tvg_Canvas from pushed paints. If free is set to true,
 392 * Tvg_Paints stored in canvas also will be released. If free is set to false,
 393 * all paints should be released manually to avoid memory leaks.
 394 * \param canvas Tvg_Canvas pointer.
 395 * \param free boolean, if equals true, function release all paints stored in given canvas.
 396 * \return
 397 * - TVG_RESULT_SUCCESS: if ok.
 398 * - TVG_RESULT_INVALID_PARAMETERS: if canvas is invalid
 399 */
 400 TVG_EXPORT Tvg_Result tvg_canvas_clear(Tvg_Canvas* canvas, bool free);
 401
 402
 403 /*!
 404 * \fn TVG_EXPORT Tvg_Result tvg_canvas_update(Tvg_Canvas* canvas)
 405 * \brief The function update all paints in given canvas. Should be called before draw to
 406 * prepare shapes for rendering.
 407 * \code
 408 * //A frame drawing example. Thread safety and events implementation is skipped to show only thorvg code.
 409 *
 410 * static Tvg_Canvas *canvas = NULL;
 411 * static Tvg_Paint *rect = NULL;
 412 *
 413 * int _frame_render(void) {
 414 *   tvg_canvas_update(canvas);
 415 *   tvg_canvas_draw(canvas);
 416 *   tvg_canvas_sync(canvas);
 417 * }
 418 *
 419 * //event handler from your code or third party library
 420 * void _event_handler(event *event_data) {
 421 *   if (!event_data) return NULL;
 422 *     switch(event_data.type) {
 423 *       case EVENT_RECT_ADD:
 424 *         if (!rect) {
 425 *           tvg_shape_append_rect(shape, 10, 10, 50, 50, 0, 0);
 426 *           tvg_shape_set_stroke_width(shape, 1.0f);
 427 *           tvg_shape_set_stroke_color(shape, 255, 0, 0, 255);
 428 *           tvg_canvas_push(canvas, shape);
 429 *         }
 430 *         break;
 431 *       case EVENT_RECT_MOVE:
 432 *         if (rect) tvg_paint_translate(rect, 10.0, 10.0);
 433 *           break;
 434 *         default:
 435 *           break;
 436 *   }
 437 * }
 438 *
 439 * int main(int argc, char **argv) {
 440 *   //example handler from your code or third party lib
 441 *   event_handler_add(handler, _event_handler);
 442 *
 443 *   //create frame rendering process which calls _frame_render() function.
 444 *   app_loop_begin(_frame_render);
 445 *   app_loop_finish();
 446 *   cleanup();
 447 * }
 448 * \endcode
 449 * \param[in] canvas Tvg_Canvas pointer
 450 * \return Tvg_Result return value
 451 * - TVG_RESULT_SUCCESS: if ok.
 452 * - TVG_RESULT_INVALID_PARAMETERS: if canvas is invalid]
 453 */
 454 TVG_EXPORT Tvg_Result tvg_canvas_update(Tvg_Canvas* canvas);
 455
 456
 457 /*!
 458 * \fn TVG_EXPORT Tvg_Result tvg_canvas_update_paint(Tvg_Canvas* canvas, Tvg_Paint* paint)
 459 * \brief The funciton updates shape before rendering. If a client application using the
 460 * thorvg library does not update the entire canvas (tvg_canvas_update()) in the frame
 461 * rendering process, Tvg_Paints previosly added to the canvas should be updated manually
 462 * using this function.
 463 * \param[in] canvas Tvg_Canvas pointer
 464 * \param[in] paint Tvg_Paint pointer to update
 465 * \return Tvg_Result return value
 466 * - TVG_RESULT_SUCCESS: if ok.
 467 * - TVG_RESULT_INVALID_PARAMETERS: if canvas is invalid
 468 */
 469 TVG_EXPORT Tvg_Result tvg_canvas_update_paint(Tvg_Canvas* canvas, Tvg_Paint* paint);
 470
 471
 472 /*!
 473 * \fn TVG_EXPORT Tvg_Result tvg_canvas_draw(Tvg_Canvas* canvas)
 474 * \brief The function start rendering process. All shapes from the given canvas will be rasterized
 475 * to the buffer.
 476 * \param[in] canvas
 477 * \return Tvg_Result return value
 478 * - TVG_RESULT_SUCCESS: if ok.
 479 * - TVG_RESULT_INSUFFICIENT_CONDITION: interna rendering errors.
 480 * - TVG_RESULT_INVALID_PARAMETERS: if canvas is invalid.
 481 */
 482 TVG_EXPORT Tvg_Result tvg_canvas_draw(Tvg_Canvas* canvas);
 483
 484
 485 /*!
 486 * \fn TVG_EXPORT Tvg_Result tvg_canvas_sync(Tvg_Canvas* canvas)
 487 * \brief The function finalize rendering process. It should be called after tvg_canvas_draw(canvas).
 488 * \param[in] canvas
 489 * \return Tvg_Result return value
 490 * - TVG_RESULT_SUCCESS: if ok.
 491 * - TVG_RESULT_INVALID_PARAMETERS: if canvas is invalids.
 492 */
 493 TVG_EXPORT Tvg_Result tvg_canvas_sync(Tvg_Canvas* canvas);
 494
 495 /* \} */
 496
 497 /**
 498 * \defgroup ThorVGCapi_Paint Paint
 499 * \brief Functions for managing graphic elements. It enables duplication, transformation and composition.
 500 *
 501 * \{
 502 */
 503
 504 /************************************************************************/
 505 /* Paint API                                                            */
 506 /************************************************************************/
 507 /*!
 508 * \fn TVG_EXPORT Tvg_Result tvg_paint_del(Tvg_Paint* paint)
 509 * \brief The function releases given paint object. The tvg_canvas_clear(canvas, true) or tvg_canvas_del(canvas)
 510 * releases previously pushed paints internally. If this function is used, tvg_canvas_clear(canvas, false) should
 511 * be used to avoid unexpected behaviours.
 512 * \code
 513 * //example of cleanup function
 514 * Tvg_Paint *rect = NULL; //rectangle shape added in other function
 515 *
 516 * //rectangle delete API
 517 * int rectangle_delete(void) {
 518 *   if (rect) tvg_paint_del(rect);
 519 *   rect = NULL;
 520 * }
 521 *
 522 * int cleanup(void) {
 523 *   tvg_canvas_clear(canvas, false);
 524 *   tvg_canvas_del(canvas);
 525 *   canvas = NULL;
 526 * }
 527 * \endcode
 528 * \param[in] paint Tvg_Paint pointer
 529 * \return Tvg_Result return value
 530 * - TVG_RESULT_SUCCESS: if ok.
 531 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 532 */
 533 TVG_EXPORT Tvg_Result tvg_paint_del(Tvg_Paint* paint);
 534
 535
 536 /*!
 537 * \fn TVG_EXPORT Tvg_Result tvg_paint_scale(Tvg_Paint* paint, float factor)
 538 * \brief The function scales given paint using given factor.
 539 * \param[in] paint Tvg_Paint pointer
 540 * \param[in] factor double scale factor
 541 * \return Tvg_Result return value
 542 * - TVG_RESULT_SUCCESS: if ok.
 543 * - TVG_RESULT_INSUFFICENT_CONDITION: if invalid factor is used.
 544 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 545 */
 546 TVG_EXPORT Tvg_Result tvg_paint_scale(Tvg_Paint* paint, float factor);
 547
 548
 549 /*!
 550 * \fn TVG_EXPORT Tvg_Result tvg_paint_rotate(Tvg_Paint* paint, float degree)
 551 * \brief The function rotates the givent paint by the given degree.
 552 * \param[in] paint Tvg_Paint pointer
 553 * \param[in] degree double rotation degree
 554 * \return Tvg_Result return value
 555 * - TVG_RESULT_SUCCESS: if ok.
 556 * - TVG_RESULT_INSUFFICENT_CONDITION: if invalid degree is used.
 557 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid.
 558 */
 559 TVG_EXPORT Tvg_Result tvg_paint_rotate(Tvg_Paint* paint, float degree);
 560
 561
 562 /*!
 563 * \fn TVG_EXPORT Tvg_Result tvg_paint_translate(Tvg_Paint* paint, float x, float y)
 564 * \brief The function moves the given paint in the X,Y coordinate system.
 565 * \param[in] paint Tvg_Paint pointer
 566 * \param[in] x float x shift
 567 * \param[in] y float y shift
 568 * \return Tvg_Result return value
 569 * - TVG_RESULT_SUCCESS: if ok.
 570 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 571 */
 572 TVG_EXPORT Tvg_Result tvg_paint_translate(Tvg_Paint* paint, float x, float y);
 573
 574
 575 /*!
 576 * \fn TVG_EXPORT Tvg_Result tvg_paint_transform(Tvg_Paint* paint, const Tvg_Matrix* m)
 577 * \brief The function transforms given paint using transformation matrix. It could
 578 * be used to move, rotate in 2d coordinates system and rotate in 3d coordinates system
 579 * \param[in] paint Tvg_Paint pointer
 580 * \param[in] m Tvg_Matrix pointer
 581 * \return Tvg_Result return value
 582 * - TVG_RESULT_SUCCESS: if ok.
 583 * - TVG_RESULT_INVALID_PARAMETERS: if paint or m is invalid
 584 */
 585 TVG_EXPORT Tvg_Result tvg_paint_transform(Tvg_Paint* paint, const Tvg_Matrix* m);
 586
 587
 588 /*!
 589 * \fn TVG_EXPORT Tvg_Result tvg_paint_set_opacity(Tvg_Paint* paint, uint8_t opacity)
 590 * \brief The function sets opacity of paint. It could be used in Tvg_Scene to implement
 591 * translucent layers of shapes.
 592 * \param[in] paint Tvg_Paint pointer
 593 * \param[in] opacity uint8_t opacity value
 594 * \return Tvg_Result return value
 595 * - TVG_RESULT_SUCCESS: if ok.
 596 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 597 */
 598 TVG_EXPORT Tvg_Result tvg_paint_set_opacity(Tvg_Paint* paint, uint8_t opacity);
 599
 600
 601 /*!
 602 * \fn TVG_EXPORT Tvg_Result tvg_paint_get_opacity(Tvg_Paint* paint, uint8_t* opacity)
 603 * \brief The function gets opacity of given paint
 604 * \param[in] paint Tvg_Paint pointer
 605 * \param[out] opacity uint8_t pointer to store opacity
 606 * \return Tvg_Result return value
 607 * - TVG_RESULT_SUCCESS: if ok.
 608 * - TVG_RESULT_INVALID_PARAMETERS: if canvas is invalid
 609 */
 610 TVG_EXPORT Tvg_Result tvg_paint_get_opacity(Tvg_Paint* paint, uint8_t* opacity);
 611
 612
 613 /*!
 614 * \fn TVG_EXPORT Tvg_Paint* tvg_paint_duplicate(Tvg_Paint* paint)
 615 * \brief The function duplicates given paint. Returns newly allocated paint with the
 616 * same properties (stroke, color, path). It could be used to duplicate scenes too.
 617 * \param[in] paint Tvg_Paint pointer
 618 * \return Tvg_Paint pointer to duplicatede paint
 619 */
 620 TVG_EXPORT Tvg_Paint* tvg_paint_duplicate(Tvg_Paint* paint);
 621
 622
 623 /*!
 624 * \fn TVG_EXPORT Tvg_Result tvg_paint_get_bounds(const Tvg_Paint* paint, float* x, float* y, float* w, float* h)
 625 * \brief The function returns paint path bounds.
 626 * \param[in] paint Tvg_Paint pointer
 627 * \param[out] x float x position
 628 * \param[out] y float y position
 629 * \param[out] w float paint width
 630 * \param[out] h float paint height
 631 * \return Tvg_Result return value
 632 * - TVG_RESULT_SUCCESS: if ok.
 633 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 634 */
 635 TVG_EXPORT Tvg_Result tvg_paint_get_bounds(const Tvg_Paint* paint, float* x, float* y, float* w, float* h);
 636
 637 /*!
 638 * \fn TVG_EXPORT Tvg_Result tvg_paint_set_composite_method(Tvg_Paint* paint, Tvg_Paint* target, Tvg_Composite_Method method)
 639 * \brief The function set composition method.
 640 * \param[in] paint Tvg_Paint composition source
 641 * \param[in] target Tvg_Paint composition target
 642 * \param[in] method Tvg_Composite_Method used composite method
 643 * \return Tvg_Result return value
 644 * - TVG_RESULT_SUCCESS: if ok.
 645 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 646 */
 647 TVG_EXPORT Tvg_Result tvg_paint_set_composite_method(Tvg_Paint* paint, Tvg_Paint* target, Tvg_Composite_Method method);
 648
 649 /** \}*/
 650
 651 /**
 652 * \defgroup ThorVGCapi_Shape Shape
 653 * \brief Functions representing two-dimensional figures and their properties.
 654 * The shapes of the figures in the Shape object are stored as the sub-paths in the path.
 655 * The data to be saved in the path can be read directly from the svg file or through the provided APIs.
 656 *
 657 * \{
 658 */
 659
 660
 661 /************************************************************************/
 662 /* Shape API                                                            */
 663 /************************************************************************/
 664 /*!
 665 * \fn TVG_EXPORT Tvg_Paint* tvg_shape_new()
 666 * \brief The function creates a new shape
 667 * \return Tvg_Paint pointer or NULL if something went wrong
 668 */
 669 TVG_EXPORT Tvg_Paint* tvg_shape_new();
 670
 671
 672 /*!
 673 * \fn TVG_EXPORT Tvg_Result tvg_shape_reset(Tvg_Paint* paint)
 674 * \brief The function resets shape properties like path, stroke properties, fill color
 675 * \param[in] paint Tvg_Paint pointer
 676 * \return Tvg_Result return value
 677 * - TVG_RESULT_SUCCESS: if ok.
 678 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 679 */
 680 TVG_EXPORT Tvg_Result tvg_shape_reset(Tvg_Paint* paint);
 681
 682
 683 /*!
 684 * \fn TVG_EXPORT Tvg_Result tvg_shape_move_to(Tvg_Paint* paint, float x, float y)
 685 * \brief The funciton moves the current point to the given point.
 686 * \param[in] paint Tvg_paint pointer
 687 * \param[in] x move x coordinate
 688 * \param[in] y move y coordinate
 689 * \return Tvg_Result return value
 690 * - TVG_RESULT_SUCCESS: if ok.
 691 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 692 */
 693 TVG_EXPORT Tvg_Result tvg_shape_move_to(Tvg_Paint* paint, float x, float y);
 694
 695
 696 /*!
 697 * \fn TVG_EXPORT Tvg_Result tvg_shape_line_to(Tvg_Paint* paint, float x, float y)
 698 * \brief The funciton adds straight line from the current point to the given point.
 699 * \param[in] paint Tvg_Paint pointer
 700 * \param[in] x line end x position
 701 * \param[in] y line end y position
 702 * \return Tvg_Result return value
 703 * - TVG_RESULT_SUCCESS: if ok.
 704 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 705 */
 706 TVG_EXPORT Tvg_Result tvg_shape_line_to(Tvg_Paint* paint, float x, float y);
 707
 708
 709 /*!
 710 * \fn TVG_EXPORT Tvg_Result tvg_shape_cubic_to(Tvg_Paint* paint, float cx1, float cy1, float cx2, float cy2, float x, float y)
 711 * \brief The function adds a cubic Bezier curve between the current point and given end point (x, y) specified by control
 712 points (cx1, cy1) and (cx2, cy2).
 713 * \param[in] paint Tvg_Paint pointer
 714 * \param[in] cx1 First control point x coordinate
 715 * \param[in] cy1 First control point y coordinate
 716 * \param[in] cx2 Second control point x coordinate
 717 * \param[in] cy2 Second control point y coordinate
 718 * \param[in] x Line end x coordinate
 719 * \param[in] y Line end y coordinate
 720 * \return Tvg_Result return value
 721 * - TVG_RESULT_SUCCESS: if ok.
 722 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 723 */
 724 TVG_EXPORT Tvg_Result tvg_shape_cubic_to(Tvg_Paint* paint, float cx1, float cy1, float cx2, float cy2, float x, float y);
 725
 726
 727 /*!
 728 * \fn TVG_EXPORT Tvg_Result tvg_shape_close(Tvg_Paint* paint)
 729 * \brief The function closes current path by drawing line to the start position of it.
 730 * \param[in] paint
 731 * \return Tvg_Result return value
 732 * - TVG_RESULT_SUCCESS: if ok.
 733 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 734 */
 735 TVG_EXPORT Tvg_Result tvg_shape_close(Tvg_Paint* paint);
 736 /*!
 737 * \fn TVG_EXPORT Tvg_Result tvg_shape_append_rect(Tvg_Paint* paint, float x, float y, float w, float h, float rx, float ry)
 738 * \brief The function appends rectangle in start position specified by x and y parameters, size spiecified by w and h parameters
 739 * and rounded rectangles specified by rx, ry parameteres
 740 * \param[in] paint Tvg_Paint pointer
 741 * \param[in] x start x position
 742 * \param[in] y start y position
 743 * \param[in] w rectangle width
 744 * \param[in] h rectangle height
 745 * \param[in] rx rectangle corner x radius
 746 * \param[in] ry rectangle corner y radius
 747 * \return Tvg_Result return value
 748 * - TVG_RESULT_SUCCESS: if ok.
 749 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 750 */
 751 TVG_EXPORT Tvg_Result tvg_shape_append_rect(Tvg_Paint* paint, float x, float y, float w, float h, float rx, float ry);
 752
 753
 754 /*!
 755 * \fn TVG_EXPORT Tvg_Result tvg_shape_append_circle(Tvg_Paint* paint, float cx, float cy, float rx, float ry)
 756 * \brief The function appends circle with center in (cx, cy) point, x radius (rx) and y radius (ry)
 757 * \param[in] paint Tvg_Paint pointer
 758 * \param[in] cx circle x center
 759 * \param[in] cy circle y center
 760 * \param[in] rx circle x radius
 761 * \param[in] ry circle y radius
 762 * \return Tvg_Result return value
 763 * - TVG_RESULT_SUCCESS: if ok.
 764 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 765 */
 766 TVG_EXPORT Tvg_Result tvg_shape_append_circle(Tvg_Paint* paint, float cx, float cy, float rx, float ry);
 767
 768
 769 /*!
 770 * \fn TVG_EXPORT Tvg_Result tvg_shape_append_arc(Tvg_Paint* paint, float cx, float cy, float radius, float startAngle, float sweep, uint8_t pie)
 771 * \brief The function append an arc to the shape with center in (cx, cy) position. Arc radius is set by radius parameter. Start position of an
 772 * arcus is defined by startAngle variable. Arcus lenght is set by sweep parameter. To draw closed arcus pie parameter should be set to true.
 773 * \param[in] paint Tvg_Paint pointer
 774 * \param[in] cx arcus x center
 775 * \param[in] cy arcus y center
 776 * \param[in] radius radius of an arc
 777 * \param[in] startAngle start angle of an arc in degrees
 778 * \param[in] sweep lenght of an arc in degrees
 779 * \param[in] pie arcus close parameter
 780 * \return Tvg_Result return value
 781 * - TVG_RESULT_SUCCESS: if ok.
 782 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 783 */
 784 TVG_EXPORT Tvg_Result tvg_shape_append_arc(Tvg_Paint* paint, float cx, float cy, float radius, float startAngle, float sweep, uint8_t pie);
 785
 786
 787 /*!
 788 * \fn TVG_EXPORT Tvg_Result tvg_shape_append_path(Tvg_Paint* paint, const Tvg_Path_Command* cmds, uint32_t cmdCnt, const Tvg_Point* pts, uint32_t ptsCnt)
 789 * \brief The function append path specified by path commands and path points
 790 * \param[in] paint Tvg_Paint pointer
 791 * \param[in] cmds array of path commands
 792 * \param[in] cmdCnt lenght of commands array
 793 * \param[in] pts array of command points
 794 * \param[in] ptsCnt lenght of command points array
 795 * \return Tvg_Result return value
 796 * - TVG_RESULT_SUCCESS: if ok.
 797 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 798 */
 799 TVG_EXPORT Tvg_Result tvg_shape_append_path(Tvg_Paint* paint, const Tvg_Path_Command* cmds, uint32_t cmdCnt, const Tvg_Point* pts, uint32_t ptsCnt);
 800
 801
 802 /*!
 803 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_path_coords(const Tvg_Paint* paint, const Tvg_Point** pts, uint32_t* cnt)
 804 * \brief The function get path coordinates to the Tvg_Point array. Array length is specified by cnt output parameter.
 805 * The function does not allocate any data, it operates on internal memory. There is no need to free pts array.
 806 * \code
 807 * Tvg_Shape *shape = tvg_shape_new();
 808 * Tvg_Point *coords = NULL;
 809 * uint32_t len = 0;
 810 *
 811 * tvg_shape_append_circle(shape, 10, 10, 50, 50);
 812 * tvg_shape_get_path_coords(shape, (const Tvg_Point**)&coords, &coords_len);
 813 * //thorvg aproximates circle by four Bezier lines. In example above cmds array will store their coordinates
 814 * \endcode
 815 * \param[in] paint Tvg_Paint pointer
 816 * \param[out] pts points output array
 817 * \param[out] cnt points array length
 818 * \return Tvg_Result return value
 819 * - TVG_RESULT_SUCCESS: if ok.
 820 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 821 */
 822 TVG_EXPORT Tvg_Result tvg_shape_get_path_coords(const Tvg_Paint* paint, const Tvg_Point** pts, uint32_t* cnt);
 823
 824
 825 /*!
 826 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_path_commands(const Tvg_Paint* paint, const Tvg_Path_Command** cmds, uint32_t* cnt)
 827 * \brief The function gets path commands to commands array. Array length is specified by cnt output parameter.
 828 * The function does not allocate any data. There is no need to cmds array.
 829 * \code
 830 * Tvg_Shape *shape = tvg_shape_new();
 831 * Tvg_Point *coords = NULL;
 832 * uint32_t len = 0;
 833 *
 834 * tvg_shape_append_circle(shape, 10, 10, 50, 50);
 835 * tvg_shape_get_path_commands(shape, (const Tvg_Path_Command**)&cmds, &len);
 836 * //thorvg aproximates circle by four Bezier lines. In example above cmds array will store their coordinates
 837 * \endcode
 838 * \param[in] paint Tvg_Paint pointer
 839 * \param[out] cmds commands output array
 840 * \param[out] cnt commands array length
 841 * \return Tvg_Result return value
 842 * - TVG_RESULT_SUCCESS: if ok.
 843 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 844 */
 845 TVG_EXPORT Tvg_Result tvg_shape_get_path_commands(const Tvg_Paint* paint, const Tvg_Path_Command** cmds, uint32_t* cnt);
 846
 847
 848 /*!
 849 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_stroke_width(Tvg_Paint* paint, float width)
 850 * \brief The function sets shape's stroke width.
 851 * \param[in] paint Tvg_Paint pointer
 852 * \param[in] width stroke width parameter
 853 * \return Tvg_Result return value
 854 * - TVG_RESULT_SUCCESS: if ok.
 855 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 856 */
 857 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_width(Tvg_Paint* paint, float width);
 858
 859
 860 /*!
 861 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_stroke_width(const Tvg_Paint* paint, float* width)
 862 * \brief The function gets shape's stroke width
 863 * \param[in] paint Tvg_Paint pointer
 864 * \param[out] width stroke width
 865 * \return Tvg_Result return value
 866 * - TVG_RESULT_SUCCESS: if ok.
 867 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 868 */
 869 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_width(const Tvg_Paint* paint, float* width);
 870
 871
 872 /*!
 873 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_stroke_color(Tvg_Paint* paint, uint8_t r, uint8_t g, uint8_t b, uint8_t a)
 874 * \brief The function sets shape's stroke color.
 875 * \param[in] paint Tvg_Paint pointer
 876 * \param[in] r red value
 877 * \param[in] g green value
 878 * \param[in] b blue value
 879 * \param[in] a opacity value
 880 * \return Tvg_Result return value
 881 * - TVG_RESULT_SUCCESS: if ok.
 882 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 883 */
 884 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_color(Tvg_Paint* paint, uint8_t r, uint8_t g, uint8_t b, uint8_t a);
 885
 886
 887 /*!
 888 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_stroke_color(const Tvg_Paint* paint, uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a)
 889 * \brief The function gets shape's stroke color
 890 * \param[in] paint Tvg_Paint pointer
 891 * \param[out] r red value
 892 * \param[out] g green value
 893 * \param[out] b blue value
 894 * \param[out] a opacity value
 895 * \return Tvg_Result return value
 896 * - TVG_RESULT_SUCCESS: if ok.
 897 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 898 */
 899 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_color(const Tvg_Paint* paint, uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a);
 900
 901
 902 /*!
 903 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_stroke_linear_gradient(Tvg_Paint* paint, Tvg_Gradient* grad)
 904 * \brief The function inserts linear gradient object as an shape stroke.
 905 * \param[in] paint Tvg_Paint pointer
 906 * \param[in] grad Tvg_Gradient pointer (linear)
 907 * \return Tvg_Result return value
 908 * - TVG_RESULT_SUCCESS: if ok.
 909 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 910 */
 911 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_linear_gradient(Tvg_Paint* paint, Tvg_Gradient* grad);
 912
 913
 914 /*!
 915 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_stroke_radial_gradient(Tvg_Paint* paint, Tvg_Gradient* grad)
 916 * \brief The function inserts radial gradient object as an shape stroke.
 917 * \param[in] paint Tvg_Paint pointer
 918 * \param[in] grad Tvg_Gradient pointer
 919 * \return Tvg_Result return value
 920 * - TVG_RESULT_SUCCESS: if ok.
 921 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 922 */
 923 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_radial_gradient(Tvg_Paint* paint, Tvg_Gradient* grad);
 924
 925
 926 /*!
 927 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_stroke_gradient(const Tvg_Paint* paint, Tvg_Gradient** grad)
 928 * \brief The function returns gradient previously inserted to given shape stroke. Function deos not
 929 * allocate any data.
 930 * \param[in] paint Tvg_Paint pointer
 931 * \param[out] grad Tvg_Gradient pointer
 932 * \return Tvg_Result return value
 933 * - TVG_RESULT_SUCCESS: if ok.
 934 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 935 */
 936 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_gradient(const Tvg_Paint* paint, Tvg_Gradient** grad);
 937
 938
 939 /*!
 940 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_stroke_dash(Tvg_Paint* paint, const float* dashPattern, uint32_t cnt)
 941 * \brief The function sets shape's stroke dash mode. Dash pattern is an array of floats with size which have to be
 942 * divisible by 2. Position with index not divisible by 2 defines length of line. Positions divisible by 2 defines
 943 * length of gap
 944 * \code
 945 * //dash pattern examples
 946 * float dashPattern[2] = {20, 10};  // -- - -- - -- -
 947 * float dashPattern[2] = {40, 20};  // ----  ----  ----
 948 * float dashPattern[4] = {10, 20, 30, 40} // -  ---
 949 * \endcode
 950 * \param[in] paint Tvg_Paint pointer
 951 * \param[in] dashPattern array of floats descibing pattern [(line, gap)]
 952 * \param[in] cnt size of an array
 953 * \return Tvg_Result return value
 954 * - TVG_RESULT_SUCCESS: if ok.
 955 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 956 */
 957 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_dash(Tvg_Paint* paint, const float* dashPattern, uint32_t cnt);
 958
 959
 960 /*!
 961 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_stroke_dash(const Tvg_Paint* paint, const float** dashPattern, uint32_t* cnt)
 962 * \brief The function returns shape's stroke dash pattern and its size.
 963 * \see tvg_shape_set_stroke_dash
 964 * \param[in] paint Tvg_Paint pointer
 965 * \param[out] dashPattern array of floats describing pattern
 966 * \param[out] cnt size of an array
 967 * \return Tvg_Result return value
 968 * - TVG_RESULT_SUCCESS: if ok.
 969 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 970 */
 971 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_dash(const Tvg_Paint* paint, const float** dashPattern, uint32_t* cnt);
 972
 973
 974 /*!
 975 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_stroke_cap(Tvg_Paint* paint, Tvg_Stroke_Cap cap)
 976 * \brief The function sets the stroke capabilities style to be used for stroking the path.
 977 * \see Tvg_Stroke_Cap
 978 * \see tvg_shape_get_stroke_cap
 979 * \param[in] paint Tvg_Paint pointer
 980 * \param[in] cap stroke capabilities
 981 * \return Tvg_Result return value
 982 * - TVG_RESULT_SUCCESS: if ok.
 983 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 984 */
 985 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_cap(Tvg_Paint* paint, Tvg_Stroke_Cap cap);
 986
 987
 988 /*!
 989 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_stroke_cap(const Tvg_Paint* paint, Tvg_Stroke_Cap* cap)
 990 * \brief The function gets the stroke capabilities.
 991 * \see Tvg_Stroke_Cap
 992 * \see tvg_shape_set_stroke_cap
 993 * \param[in] paint Tvg_Paint pointer
 994 * \param[out] cap stroke capabilities
 995 * \return Tvg_Result return value
 996 * - TVG_RESULT_SUCCESS: if ok.
 997 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
 998 */
 999 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_cap(const Tvg_Paint* paint, Tvg_Stroke_Cap* cap);
1000
1001
1002 /*!
1003 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_stroke_join(Tvg_Paint* paint, Tvg_Stroke_Join join)
1004 * \brief The function sets the stroke join method.
1005 * \see Tvg_Stroke_Join
1006 * \see tvg_shape_set_stroke_cap
1007 * \param[in] paint Tvg_Paint pointer
1008 * \param[in] join join method
1009 * \return Tvg_Result return value
1010 * - TVG_RESULT_SUCCESS: if ok.
1011 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1012 */
1013 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_join(Tvg_Paint* paint, Tvg_Stroke_Join join);
1014
1015
1016 /*!
1017 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_stroke_join(const Tvg_Paint* paint, Tvg_Stroke_Join* join)
1018 * \brief The function gets the stroke join method
1019 * \param[in] paint Tvg_Paint pointer
1020 * \param[out] join join method
1021 * \return Tvg_Result return value
1022 * - TVG_RESULT_SUCCESS: if ok.
1023 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1024 */
1025 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_join(const Tvg_Paint* paint, Tvg_Stroke_Join* join);
1026
1027
1028 /*!
1029 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_fill_color(Tvg_Paint* paint, uint8_t r, uint8_t g, uint8_t b, uint8_t a)
1030 * \brief The function sets shape's fill color.
1031 * \see tvg_shape_get_fill_color
1032 * \param[in] paint Tvg_Paint pointer
1033 * \param[in] r red value
1034 * \param[in] g green value
1035 * \param[in] b blue value
1036 * \param[in] a alpha value
1037 * \return Tvg_Result return value
1038 * - TVG_RESULT_SUCCESS: if ok.
1039 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1040 */
1041 TVG_EXPORT Tvg_Result tvg_shape_set_fill_color(Tvg_Paint* paint, uint8_t r, uint8_t g, uint8_t b, uint8_t a);
1042
1043
1044 /*!
1045 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_fill_color(const Tvg_Paint* paint, uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a)
1046 * \brief The function gets shape's fill color
1047 * \see tvg_shape_set_fill_color
1048 * \param[in] paint Tvg_Paint pointer
1049 * \param[out] r red value
1050 * \param[out] g green value
1051 * \param[out] b blue value
1052 * \param[out] a alpha value
1053 * \return Tvg_Result return value
1054 * - TVG_RESULT_SUCCESS: if ok.
1055 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1056 */
1057 TVG_EXPORT Tvg_Result tvg_shape_get_fill_color(const Tvg_Paint* paint, uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a);
1058
1059
1060 /*!
1061 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_fill_rule(Tvg_Paint* paint, Tvg_Fill_Rule rule)
1062 * \brief The function sets shape's fill rule.  TVG_FILL_RULE_WINDING is used as default fill rule
1063 * \see \link Wiki https://en.wikipedia.org/wiki/Nonzero-rule \endlink
1064 * \param[in] paint Tvg_Paint pointer
1065 * \param[in] rule fill rule
1066 * \return Tvg_Result return value
1067 * - TVG_RESULT_SUCCESS: if ok.
1068 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1069 */
1070 TVG_EXPORT Tvg_Result tvg_shape_set_fill_rule(Tvg_Paint* paint, Tvg_Fill_Rule rule);
1071
1072
1073 /*!
1074 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_fill_rule(const Tvg_Paint* paint, Tvg_Fill_Rule* rule)
1075 * \brief The function gets shape's fill rule.
1076 * \see tvg_shape_get_fill_rule
1077 * \param[in] paint Tvg_Paint pointer
1078 * \param[out] rule shape's fill rule
1079 * \return Tvg_Result return value
1080 * - TVG_RESULT_SUCCESS: if ok.
1081 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1082 */
1083 TVG_EXPORT Tvg_Result tvg_shape_get_fill_rule(const Tvg_Paint* paint, Tvg_Fill_Rule* rule);
1084
1085
1086 /*!
1087 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_linear_gradient(Tvg_Paint* paint, Tvg_Gradient* grad)
1088 * \brief The function inserts linear gradient object as an shape fill.
1089 * \code
1090 * Tvg_Gradient* grad = tvg_linear_gradient_new();
1091 * tvg_linear_gradient_set(grad, 700, 700, 800, 800);
1092 * tvg_shape_set_linear_gradient(shape, grad);
1093 * \endcode
1094 * \param[in] paint Tvg_Paint pointer
1095 * \param[in] grad Tvg_Gradient pointer (linear)
1096 * \return Tvg_Result return value
1097 * - TVG_RESULT_SUCCESS: if ok.
1098 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1099 */
1100 TVG_EXPORT Tvg_Result tvg_shape_set_linear_gradient(Tvg_Paint* paint, Tvg_Gradient* grad);
1101
1102
1103 /*!
1104 * \fn TVG_EXPORT Tvg_Result tvg_shape_set_radial_gradient(Tvg_Paint* paint, Tvg_Gradient* grad)
1105 * \brief The function inserts radial gradient object as an shape fill.
1106 * \code
1107 * Tvg_Gradient* grad = tvg_radial_gradient_new();
1108 * tvg_radial_gradient_set(grad, 550, 550, 50));
1109 * tvg_shape_set_radial_gradient(shape, grad);
1110 * \endcode
1111 * \param[in] paint Tvg_Paint pointer
1112 * \param[in] grad Tvg_Gradient pointer
1113 * \return Tvg_Result return value
1114 * - TVG_RESULT_SUCCESS: if ok.
1115 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1116 */
1117 TVG_EXPORT Tvg_Result tvg_shape_set_radial_gradient(Tvg_Paint* paint, Tvg_Gradient* grad);
1118
1119
1120 /*!
1121 * \fn TVG_EXPORT Tvg_Result tvg_shape_get_gradient(const Tvg_Paint* paint, Tvg_Gradient** grad)
1122 * \brief The function returns gradient previously inserted to given shape. Function deos not
1123 * allocate any data.
1124 * \param[in] paint Tvg_Paint pointer
1125 * \param[out] grad Tvg_Gradient pointer
1126 * \return Tvg_Result return value
1127 * - TVG_RESULT_SUCCESS: if ok.
1128 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1129 */
1130 TVG_EXPORT Tvg_Result tvg_shape_get_gradient(const Tvg_Paint* paint, Tvg_Gradient** grad);
1131
1132 /** \}*/
1133
1134 /**
1135 * \defgroup ThorVGCapi_Gradient Gradient
1136 * \brief Functions representing the gradient fill of the Shape object.
1137 *
1138 * It contains the information about the gradient colors and their arrangement
1139 * inside the gradient bounds. The gradients bounds are defined in the LinearGradient
1140 * or RadialGradient class, depending on the type of the gradient to be used.
1141 * It specifies the gradient behavior in case the area defined by the gradient bounds
1142 * is smaller than the area to be filled.
1143 *
1144 * \{
1145 */
1146
1147 /************************************************************************/
1148 /* Gradient API                                                         */
1149 /************************************************************************/
1150 /*!
1151 * \fn TVG_EXPORT Tvg_Gradient* tvg_linear_gradient_new()
1152 * \brief The function creates new linear gradient object.
1153 * \code
1154 * Tvg_Paint shape = tvg_shape_new();
1155 * tvg_shape_append_rect(shape, 700, 700, 100, 100, 20, 20);
1156 * Tvg_Gradient* grad = tvg_linear_gradient_new();
1157 * tvg_linear_gradient_set(grad, 700, 700, 800, 800);
1158 * Tvg_Color_Stop color_stops[2] =
1159 * {
1160 *   {.offset=0, .r=0, .g=0, .b=0,   .a=255},
1161 *   {.offset=1, .r=0, .g=255, .b=0, .a=255},
1162 * };
1163 * tvg_gradient_set_color_stops(grad, color_stops, 2);
1164 * tvg_shape_set_linear_gradient(shape, grad);
1165 * \endcode
1166 * \return Tvg_Result return value
1167 * - TVG_RESULT_SUCCESS: if ok.
1168 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1169 */
1170 TVG_EXPORT Tvg_Gradient* tvg_linear_gradient_new();
1171
1172
1173 /*!
1174 * \fn TVG_EXPORT Tvg_Gradient* tvg_radial_gradient_new()
1175 * \brief The function creates new gradient object.
1176 * \code
1177 * Tvg_Paint shape = tvg_shape_new();
1178 * tvg_shape_append_rect(shape, 700, 700, 100, 100, 20, 20);
1179 * Tvg_Gradient* grad = tvg_radial_gradient_new();
1180 * tvg_linear_gradient_set(grad, 550, 550, 50);
1181 * Tvg_Color_Stop color_stops[2] =
1182 * {
1183 *   {.offset=0, .r=0, .g=0, .b=0,   .a=255},
1184 *   {.offset=1, .r=0, .g=255, .b=0, .a=255},
1185 * };
1186 * tvg_gradient_set_color_stops(grad, color_stops, 2);
1187 * tvg_shape_set_radial_gradient(shape, grad);
1188 * \endcode
1189 * \return Tvg_Result return value
1190 * - TVG_RESULT_SUCCESS: if ok.
1191 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1192 */
1193 TVG_EXPORT Tvg_Gradient* tvg_radial_gradient_new();
1194
1195
1196 /*!
1197 * \fn TVG_EXPORT Tvg_Result tvg_linear_gradient_set(Tvg_Gradient* grad, float x1, float y1, float x2, float y2)
1198 * \brief The function sets start (x1, y1) and end point (x2, y2) of the gradient.
1199 * \param[in] grad Tvg_Gradient pointer
1200 * \param[in] x1 start point x coordinate
1201 * \param[in] y1 start point y coordinate
1202 * \param[in] x2 end point x coordinate
1203 * \param[in] y2 end point y coordinate
1204 * \return Tvg_Result return value
1205 * - TVG_RESULT_SUCCESS: if ok.
1206 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1207 */
1208 TVG_EXPORT Tvg_Result tvg_linear_gradient_set(Tvg_Gradient* grad, float x1, float y1, float x2, float y2);
1209
1210
1211 /*!
1212 * \fn TVG_EXPORT Tvg_Result tvg_linear_gradient_get(Tvg_Gradient* grad, float* x1, float* y1, float* x2, float* y2)
1213 * \brief The function gets linear gradient start and end postion.
1214 * \param[in] grad Tvg_Gradient pointer
1215 * \param[out] x1 start point x coordinate
1216 * \param[out] y1 start point y coordinate
1217 * \param[out] x2 end point x coordinate
1218 * \param[out] y2 end point y coordinate
1219 * \return Tvg_Result return value
1220 * - TVG_RESULT_SUCCESS: if ok.
1221 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1222 */
1223 TVG_EXPORT Tvg_Result tvg_linear_gradient_get(Tvg_Gradient* grad, float* x1, float* y1, float* x2, float* y2);
1224
1225
1226 /*!
1227 * \fn TVG_EXPORT Tvg_Result tvg_radial_gradient_set(Tvg_Gradient* grad, float cx, float cy, float radius)
1228 * \brief The function sets radial gradient center and radius
1229 * \param[in] grad Tvg_Gradient pointer
1230 * \param[in] cx radial gradient center x coordinate
1231 * \param[in] cy radial gradient center y coordinate
1232 * \param[in] radius radial gradient radius value
1233 * \return Tvg_Result return value
1234 * - TVG_RESULT_SUCCESS: if ok.
1235 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1236 */
1237 TVG_EXPORT Tvg_Result tvg_radial_gradient_set(Tvg_Gradient* grad, float cx, float cy, float radius);
1238
1239
1240 /*!
1241 * \fn TVG_EXPORT Tvg_Result tvg_radial_gradient_get(Tvg_Gradient* grad, float* cx, float* cy, float* radius)
1242 * \brief The function gets radial gradient center point ant radius
1243 * \param[in] grad Tvg_Gradient pointer
1244 * \param[out] cx gradient center x coordinate
1245 * \param[out] cy gradient center y coordinate
1246 * \param[out] radius gradient radius value
1247 * \return Tvg_Result return value
1248 * - TVG_RESULT_SUCCESS: if ok.
1249 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1250 */
1251 TVG_EXPORT Tvg_Result tvg_radial_gradient_get(Tvg_Gradient* grad, float* cx, float* cy, float* radius);
1252
1253 /*!
1254 * \fn TVG_EXPORT Tvg_Result tvg_gradient_set_color_stops(Tvg_Gradient* grad, const Tvg_Color_Stop* color_stop, uint32_t cnt)
1255 * \brief The function sets lists of color stops for the given gradient
1256 * \see tvg_linear_gradient_new
1257 * \param[in] grad Tvg_Gradient pointer
1258 * \param[in] color_stop color stops list
1259 * \param[in] cnt color stops size
1260 * \return Tvg_Result return value
1261 * - TVG_RESULT_SUCCESS: if ok.
1262 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1263 */
1264 TVG_EXPORT Tvg_Result tvg_gradient_set_color_stops(Tvg_Gradient* grad, const Tvg_Color_Stop* color_stop, uint32_t cnt);
1265
1266
1267 /*!
1268 * \fn TVG_EXPORT Tvg_Result tvg_gradient_get_color_stops(Tvg_Gradient* grad, const Tvg_Color_Stop** color_stop, uint32_t* cnt)
1269 * \brief The function gets lists of color stops for the given gradient
1270 * \param[in] grad Tvg_Gradient pointer
1271 * \param[out] color_stop color stops list
1272 * \param[out] cnt color stops list size
1273 * \return Tvg_Result return value
1274 * - TVG_RESULT_SUCCESS: if ok.
1275 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1276 */
1277 TVG_EXPORT Tvg_Result tvg_gradient_get_color_stops(Tvg_Gradient* grad, const Tvg_Color_Stop** color_stop, uint32_t* cnt);
1278
1279
1280 /*!
1281 * \fn TVG_EXPORT Tvg_Result tvg_gradient_set_spread(Tvg_Gradient* grad, const Tvg_Stroke_Fill spread)
1282 * \brief The function sets spread fill method for given gradient
1283 * \param[in] grad Tvg_Gradient pointer
1284 * \param[in] spread spread method
1285 * \return Tvg_Result return value
1286 * - TVG_RESULT_SUCCESS: if ok.
1287 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1288 */
1289 TVG_EXPORT Tvg_Result tvg_gradient_set_spread(Tvg_Gradient* grad, const Tvg_Stroke_Fill spread);
1290
1291
1292 /*!
1293 * \fn TVG_EXPORT Tvg_Result tvg_gradient_get_spread(Tvg_Gradient* grad, Tvg_Stroke_Fill* spread)
1294 * \brief The function gets spread fill method for given gradient
1295 * \param[in] grad Tvg_Gradient pointer
1296 * \param[out] spread spread method
1297 * \return Tvg_Result return value
1298 * - TVG_RESULT_SUCCESS: if ok.
1299 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1300 */
1301 TVG_EXPORT Tvg_Result tvg_gradient_get_spread(Tvg_Gradient* grad, Tvg_Stroke_Fill* spread);
1302
1303
1304 /*!
1305 * \fn TVG_EXPORT Tvg_Result tvg_gradient_del(Tvg_Gradient* grad)
1306 * \brief The function deletes given gradient object
1307 * \param[in] grad Tvg_Gradient pointer
1308 * \return Tvg_Result return value
1309 * - TVG_RESULT_SUCCESS: if ok.
1310 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1311 */
1312 TVG_EXPORT Tvg_Result tvg_gradient_del(Tvg_Gradient* grad);
1313
1314 /** \}*/
1315
1316 /**
1317 * \defgroup ThorVGCapi_Picture Picture
1318 * \brief Functions class representing an image read in one of the supported formats: svg, png and raw.
1319 * Besides the methods inherited from the Paint, it provides methods to load the image,
1320 * to change its size and to get the basic information.
1321 *
1322 * \{
1323 */
1324
1325
1326 /************************************************************************/
1327 /* Picture API                                                          */
1328 /************************************************************************/
1329 /*!
1330 * \fn TVG_EXPORT Tvg_Paint* tvg_picture_new()
1331 * \brief The function creates new picture object.
1332 * \return Tvg_Result return value
1333 * - TVG_RESULT_SUCCESS: if ok.
1334 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1335 */
1336 TVG_EXPORT Tvg_Paint* tvg_picture_new();
1337
1338
1339 /*!
1340 * \fn TVG_EXPORT Tvg_Result tvg_picture_load(Tvg_Paint* paint, const char* path)
1341 * \brief The function loads image into given paint object
1342 * \param[in] paint Tvg_Paint pointer
1343 * \param[in] path absolute path to the image file
1344 * \return Tvg_Result return value
1345 * - TVG_RESULT_SUCCESS: if ok.
1346 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1347 */
1348 TVG_EXPORT Tvg_Result tvg_picture_load(Tvg_Paint* paint, const char* path);
1349
1350
1351 /*!
1352 * \fn TVG_EXPORT Tvg_Result tvg_picture_load_raw(Tvg_Paint* paint, uint32_t *data, uint32_t w, uint32_t h, bool copy)
1353 * \brief The function loads raw image data into given paint object.
1354 * \param[in] paint Tvg_Paint pointer
1355 * \param[in] data raw data pointer
1356 * \param[in] w picture width
1357 * \param[in] h picture height
1358 * \param[in] copy if copy is set to true function copies data into the paint
1359 * \return Tvg_Result return value
1360 * - TVG_RESULT_SUCCESS: if ok.
1361 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1362 */
1363 TVG_EXPORT Tvg_Result tvg_picture_load_raw(Tvg_Paint* paint, uint32_t *data, uint32_t w, uint32_t h, bool copy);
1364
1365
1366 /*!
1367 * \fn TVG_EXPORT Tvg_Result tvg_picture_get_viewbox(const Tvg_Paint* paint, float* x, float* y, float* w, float* h)
1368 * \brief The function returns viewbox coordinates and size for given paint
1369 * \param[in] paint Tvg_Paint pointer
1370 * \param[out] x left top corner x coordinate
1371 * \param[out] y left top corner y coordinate
1372 * \param[out] w viewbox width
1373 * \param[out] h viewbox height
1374 * \return Tvg_Result return value
1375 * - TVG_RESULT_SUCCESS: if ok.
1376 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1377 */
1378 TVG_EXPORT Tvg_Result tvg_picture_get_viewbox(const Tvg_Paint* paint, float* x, float* y, float* w, float* h);
1379
1380 /** \}*/
1381
1382 /**
1383 * \defgroup ThorVGCapi_Scene Scene
1384 * \brief Functions enabling to hold many Paint objects.
1385 *
1386 * As a whole they can be transformed, their transparency can be changed, or the composition
1387 * methods may be used to all of them at once.
1388 *
1389 * \{
1390 */
1391
1392 /************************************************************************/
1393 /* Scene API                                                            */
1394 /************************************************************************/
1395 /*!
1396 * \fn TVG_EXPORT Tvg_Paint* tvg_scene_new()
1397 * \brief The function creates new scene object. Scene object is used to group paints
1398 * into one object which can be manipulated using Tvg_Paint API.
1399 * \return Tvg_Paint pointer to newly allocated scene or NULL if something went wrong
1400 */
1401 TVG_EXPORT Tvg_Paint* tvg_scene_new();
1402
1403
1404 /*!
1405 * \fn TVG_EXPORT Tvg_Result tvg_scene_reserve(Tvg_Paint* scene, uint32_t size)
1406 * \brief The function reserves a space in given space for specific number of paints
1407 * \see tvg_canvas_reserve
1408 * \param[in] scene Tvg_Paint pointer
1409 * \param[in] size size to allocate
1410 * \return Tvg_Result return value
1411 * - TVG_RESULT_SUCCESS: if ok.
1412 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1413 */
1414 TVG_EXPORT Tvg_Result tvg_scene_reserve(Tvg_Paint* scene, uint32_t size);
1415
1416
1417 /*!
1418 * \fn TVG_EXPORT Tvg_Result tvg_scene_push(Tvg_Paint* scene, Tvg_Paint* paint)
1419 * \brief The function inserts given paint in the specified scene.
1420 * \see tvg_canvas_push
1421 * \param[in] scene Tvg_Paint pointer (scene)
1422 * \param[in] paint Tvg_Paint pointer (paint)
1423 * \return Tvg_Result return value
1424 * - TVG_RESULT_SUCCESS: if ok.
1425 * - TVG_RESULT_INVALID_PARAMETERS: if paint or scene is invalid
1426 */
1427 TVG_EXPORT Tvg_Result tvg_scene_push(Tvg_Paint* scene, Tvg_Paint* paint);
1428
1429
1430 /*!
1431 * \fn TVG_EXPORT Tvg_Result tvg_scene_clear(Tvg_Paint* scene)
1432 * \brief The function claers paints inserted in scene
1433 * \see tvg_canvas_clear
1434 * \param scene Tvg_Paint pointer
1435 * \return Tvg_Result return value
1436 * - TVG_RESULT_SUCCESS: if ok.
1437 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1438 */
1439 TVG_EXPORT Tvg_Result tvg_scene_clear(Tvg_Paint* scene);
1440 /** \}*/
1441
1442 /** \}*/
1443
1444 #ifdef __cplusplus
1445 }
1446 #endif
1447
1448 #endif //_THORVG_CAPI_H_