3 * \brief Function provides C bindings for thorvg library.
4 * Please refer to src/examples/Capi.cpp to find thorvg_capi examples.
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
16 #ifndef __THORVG_CAPI_H__
17 #define __THORVG_CAPI_H__
19 /*! Importation of librairies*/
27 #define TVG_EXPORT __attribute__ ((visibility ("default")))
37 typedef struct _Tvg_Canvas Tvg_Canvas;
38 typedef struct _Tvg_Paint Tvg_Paint;
39 typedef struct _Tvg_Gradient Tvg_Gradient;
42 * \defgroup ThorVGCapi C APIs
43 * \brief ThorVG provides C interface.
49 * \defgroup ThorVGCapi_Initializer Initializer
50 * \brief Enables initialization and termination of the ThorVG engine.
57 * Software raster engine type.
59 #define TVG_ENGINE_SW (1 << 1)
64 * GL raster engine type.
66 #define TVG_ENGINE_GL (1 << 2)
71 * \ingroup ThorVGCapi_Canvas
72 * \def TVG_COLORSPACE_ABGR8888
73 * Colorspace used to fill buffer.
75 #define TVG_COLORSPACE_ABGR8888 0
79 * \ingroup ThorVGCapi_Canvas
80 * \def TVG_COLORSPACE_ARGB8888
81 * Colorspace used to fill buffer.
83 #define TVG_COLORSPACE_ARGB8888 1
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,
98 TVG_PATH_COMMAND_CLOSE = 0,
99 TVG_PATH_COMMAND_MOVE_TO,
100 TVG_PATH_COMMAND_LINE_TO,
101 TVG_PATH_COMMAND_CUBIC_TO
106 TVG_STROKE_CAP_SQUARE = 0,
107 TVG_STROKE_CAP_ROUND,
113 TVG_STROKE_JOIN_BEVEL = 0,
114 TVG_STROKE_JOIN_ROUND,
115 TVG_STROKE_JOIN_MITER
120 TVG_STROKE_FILL_PAD = 0,
121 TVG_STROKE_FILL_REFLECT,
122 TVG_STROKE_FILL_REPEAT
127 TVG_FILL_RULE_WINDING = 0,
128 TVG_FILL_RULE_EVEN_ODD
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;
161 /************************************************************************/
163 /************************************************************************/
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
170 * tvg_engine_init(TVG_ENGINE_SW, 0); //Initialize software renderer and use 1 thread
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.
184 TVG_EXPORT Tvg_Result tvg_engine_init(unsigned engine_method, unsigned threads);
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
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);
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.
208 TVG_EXPORT Tvg_Result tvg_engine_term(unsigned engine_method);
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.
220 * \defgroup ThorVGCapi_SwCanvas SwCanvas
221 * \ingroup ThorVGCapi_Canvas
222 * \brief Functions for the rasterisation of graphic elements with a software engine.
227 /************************************************************************/
229 /************************************************************************/
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)
235 * Tvg_Canvas *canvas = NULL;
237 * tvg_engine_init(TVG_ENGINE_SW, 4);
238 * canvas = tvg_swcavnas_create();
240 * //setup canvas buffer
241 * uint32_t *buffer = NULL;
242 * buffer = (uint32_t*) malloc(sizeof(uint32_t) * 100 * 100);
243 * if (!buffer) return;
245 * tvg_swcanvas_set_target(canvas, buffer, 100, 100, 100, TVG_COLORSPACE_ARGB8888);
247 * //add paints to canvas and setup them before draw calls
249 * tvg_canvas_destroy(canvas);
250 * tvg_engine_term(TVG_ENGINE_SW);
252 * \return Tvg_Canvas pointer to the canvas object, or NULL if something went wrong
256 TVG_EXPORT Tvg_Canvas* tvg_swcanvas_create();
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
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);
281 /************************************************************************/
282 /* Common Canvas API */
283 /************************************************************************/
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.
292 * static Tvg_Canvas *canvas = NULL;
293 * static uint32_t *buffer = NULL;
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);
301 * //a task called from main function in a loop
302 * static void _job(const int cmd) {
304 * case CMD_EXIT: return 0;
306 * //define valid rectangle shape
307 * tvg_canvas_push(canvas, rect);
310 * tvg_shape_del(rect);
311 * //now to safely delete Tvg_Canvas, tvg_canvas_clear() API have to be used.
318 * int main(int argc, char **argv) {
322 * tvg_engine_init(TVG_ENGINE_SW, 4);
325 * //wait for command e.g. from console
328 * tvg_canvas_clear(canvas, false);
329 * tvg_canvas_destroy(canvas);
330 * tvg_engine_term(TVG_ENGINE_SW);
335 * tvg_canvas_destroy(canvas);
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.
343 TVG_EXPORT Tvg_Result tvg_canvas_destroy(Tvg_Canvas* canvas);
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.
356 TVG_EXPORT Tvg_Result tvg_canvas_push(Tvg_Canvas* canvas, Tvg_Paint* paint);
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.
365 * Tvg_Canvas *canvas = NULL;
367 * tvg_engine_init(TVG_ENGINE_SW, 4);
368 * canvas = tvg_swcavnas_create();
370 * uint32_t *buffer = NULL;
371 * buffer = (uint32_t*) malloc(sizeof(uint32_t) * 100 * 100);
372 * if (!buffer) return;
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.
377 * tvg_canvas_destroy(canvas);
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.
386 TVG_EXPORT Tvg_Result tvg_canvas_reserve(Tvg_Canvas* canvas, uint32_t n);
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.
397 * - TVG_RESULT_SUCCESS: if ok.
398 * - TVG_RESULT_INVALID_PARAMETERS: if canvas is invalid
400 TVG_EXPORT Tvg_Result tvg_canvas_clear(Tvg_Canvas* canvas, bool free);
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.
408 * //A frame drawing example. Thread safety and events implementation is skipped to show only thorvg code.
410 * static Tvg_Canvas *canvas = NULL;
411 * static Tvg_Paint *rect = NULL;
413 * int _frame_render(void) {
414 * tvg_canvas_update(canvas);
415 * tvg_canvas_draw(canvas);
416 * tvg_canvas_sync(canvas);
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:
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);
431 * case EVENT_RECT_MOVE:
432 * if (rect) tvg_paint_translate(rect, 10.0, 10.0);
439 * int main(int argc, char **argv) {
440 * //example handler from your code or third party lib
441 * event_handler_add(handler, _event_handler);
443 * //create frame rendering process which calls _frame_render() function.
444 * app_loop_begin(_frame_render);
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]
454 TVG_EXPORT Tvg_Result tvg_canvas_update(Tvg_Canvas* canvas);
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
469 TVG_EXPORT Tvg_Result tvg_canvas_update_paint(Tvg_Canvas* canvas, Tvg_Paint* paint);
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
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.
482 TVG_EXPORT Tvg_Result tvg_canvas_draw(Tvg_Canvas* canvas);
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).
489 * \return Tvg_Result return value
490 * - TVG_RESULT_SUCCESS: if ok.
491 * - TVG_RESULT_INVALID_PARAMETERS: if canvas is invalids.
493 TVG_EXPORT Tvg_Result tvg_canvas_sync(Tvg_Canvas* canvas);
498 * \defgroup ThorVGCapi_Paint Paint
499 * \brief Functions for managing graphic elements. It enables duplication, transformation and composition.
504 /************************************************************************/
506 /************************************************************************/
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.
513 * //example of cleanup function
514 * Tvg_Paint *rect = NULL; //rectangle shape added in other function
516 * //rectangle delete API
517 * int rectangle_delete(void) {
518 * if (rect) tvg_paint_del(rect);
522 * int cleanup(void) {
523 * tvg_canvas_clear(canvas, false);
524 * tvg_canvas_del(canvas);
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
533 TVG_EXPORT Tvg_Result tvg_paint_del(Tvg_Paint* paint);
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
546 TVG_EXPORT Tvg_Result tvg_paint_scale(Tvg_Paint* paint, float factor);
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.
559 TVG_EXPORT Tvg_Result tvg_paint_rotate(Tvg_Paint* paint, float degree);
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
572 TVG_EXPORT Tvg_Result tvg_paint_translate(Tvg_Paint* paint, float x, float y);
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
585 TVG_EXPORT Tvg_Result tvg_paint_transform(Tvg_Paint* paint, const Tvg_Matrix* m);
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
598 TVG_EXPORT Tvg_Result tvg_paint_set_opacity(Tvg_Paint* paint, uint8_t opacity);
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
610 TVG_EXPORT Tvg_Result tvg_paint_get_opacity(Tvg_Paint* paint, uint8_t* opacity);
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
620 TVG_EXPORT Tvg_Paint* tvg_paint_duplicate(Tvg_Paint* paint);
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
635 TVG_EXPORT Tvg_Result tvg_paint_get_bounds(const Tvg_Paint* paint, float* x, float* y, float* w, float* h);
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
647 TVG_EXPORT Tvg_Result tvg_paint_set_composite_method(Tvg_Paint* paint, Tvg_Paint* target, Tvg_Composite_Method method);
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.
661 /************************************************************************/
663 /************************************************************************/
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
669 TVG_EXPORT Tvg_Paint* tvg_shape_new();
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
680 TVG_EXPORT Tvg_Result tvg_shape_reset(Tvg_Paint* paint);
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
693 TVG_EXPORT Tvg_Result tvg_shape_move_to(Tvg_Paint* paint, float x, float y);
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
706 TVG_EXPORT Tvg_Result tvg_shape_line_to(Tvg_Paint* paint, float x, float y);
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
724 TVG_EXPORT Tvg_Result tvg_shape_cubic_to(Tvg_Paint* paint, float cx1, float cy1, float cx2, float cy2, float x, float y);
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.
731 * \return Tvg_Result return value
732 * - TVG_RESULT_SUCCESS: if ok.
733 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
735 TVG_EXPORT Tvg_Result tvg_shape_close(Tvg_Paint* paint);
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
751 TVG_EXPORT Tvg_Result tvg_shape_append_rect(Tvg_Paint* paint, float x, float y, float w, float h, float rx, float ry);
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
766 TVG_EXPORT Tvg_Result tvg_shape_append_circle(Tvg_Paint* paint, float cx, float cy, float rx, float ry);
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
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);
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
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);
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.
807 * Tvg_Shape *shape = tvg_shape_new();
808 * Tvg_Point *coords = NULL;
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
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
822 TVG_EXPORT Tvg_Result tvg_shape_get_path_coords(const Tvg_Paint* paint, const Tvg_Point** pts, uint32_t* cnt);
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.
830 * Tvg_Shape *shape = tvg_shape_new();
831 * Tvg_Point *coords = NULL;
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
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
845 TVG_EXPORT Tvg_Result tvg_shape_get_path_commands(const Tvg_Paint* paint, const Tvg_Path_Command** cmds, uint32_t* cnt);
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
857 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_width(Tvg_Paint* paint, float width);
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
869 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_width(const Tvg_Paint* paint, float* width);
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
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);
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
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);
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
911 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_linear_gradient(Tvg_Paint* paint, Tvg_Gradient* grad);
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
923 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_radial_gradient(Tvg_Paint* paint, Tvg_Gradient* grad);
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
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
936 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_gradient(const Tvg_Paint* paint, Tvg_Gradient** grad);
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
945 * //dash pattern examples
946 * float dashPattern[2] = {20, 10}; // -- - -- - -- -
947 * float dashPattern[2] = {40, 20}; // ---- ---- ----
948 * float dashPattern[4] = {10, 20, 30, 40} // - ---
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
957 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_dash(Tvg_Paint* paint, const float* dashPattern, uint32_t cnt);
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
971 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_dash(const Tvg_Paint* paint, const float** dashPattern, uint32_t* cnt);
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
985 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_cap(Tvg_Paint* paint, Tvg_Stroke_Cap cap);
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
999 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_cap(const Tvg_Paint* paint, Tvg_Stroke_Cap* cap);
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
1013 TVG_EXPORT Tvg_Result tvg_shape_set_stroke_join(Tvg_Paint* paint, Tvg_Stroke_Join join);
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
1025 TVG_EXPORT Tvg_Result tvg_shape_get_stroke_join(const Tvg_Paint* paint, Tvg_Stroke_Join* join);
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
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);
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
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);
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
1070 TVG_EXPORT Tvg_Result tvg_shape_set_fill_rule(Tvg_Paint* paint, Tvg_Fill_Rule rule);
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
1083 TVG_EXPORT Tvg_Result tvg_shape_get_fill_rule(const Tvg_Paint* paint, Tvg_Fill_Rule* rule);
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.
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);
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
1100 TVG_EXPORT Tvg_Result tvg_shape_set_linear_gradient(Tvg_Paint* paint, Tvg_Gradient* grad);
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.
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);
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
1117 TVG_EXPORT Tvg_Result tvg_shape_set_radial_gradient(Tvg_Paint* paint, Tvg_Gradient* grad);
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
1130 TVG_EXPORT Tvg_Result tvg_shape_get_gradient(const Tvg_Paint* paint, Tvg_Gradient** grad);
1135 * \defgroup ThorVGCapi_Gradient Gradient
1136 * \brief Functions representing the gradient fill of the Shape object.
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.
1147 /************************************************************************/
1149 /************************************************************************/
1151 * \fn TVG_EXPORT Tvg_Gradient* tvg_linear_gradient_new()
1152 * \brief The function creates new linear gradient object.
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] =
1160 * {.offset=0, .r=0, .g=0, .b=0, .a=255},
1161 * {.offset=1, .r=0, .g=255, .b=0, .a=255},
1163 * tvg_gradient_set_color_stops(grad, color_stops, 2);
1164 * tvg_shape_set_linear_gradient(shape, grad);
1166 * \return Tvg_Result return value
1167 * - TVG_RESULT_SUCCESS: if ok.
1168 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1170 TVG_EXPORT Tvg_Gradient* tvg_linear_gradient_new();
1174 * \fn TVG_EXPORT Tvg_Gradient* tvg_radial_gradient_new()
1175 * \brief The function creates new gradient object.
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] =
1183 * {.offset=0, .r=0, .g=0, .b=0, .a=255},
1184 * {.offset=1, .r=0, .g=255, .b=0, .a=255},
1186 * tvg_gradient_set_color_stops(grad, color_stops, 2);
1187 * tvg_shape_set_radial_gradient(shape, grad);
1189 * \return Tvg_Result return value
1190 * - TVG_RESULT_SUCCESS: if ok.
1191 * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid
1193 TVG_EXPORT Tvg_Gradient* tvg_radial_gradient_new();
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
1208 TVG_EXPORT Tvg_Result tvg_linear_gradient_set(Tvg_Gradient* grad, float x1, float y1, float x2, float y2);
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
1223 TVG_EXPORT Tvg_Result tvg_linear_gradient_get(Tvg_Gradient* grad, float* x1, float* y1, float* x2, float* y2);
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
1237 TVG_EXPORT Tvg_Result tvg_radial_gradient_set(Tvg_Gradient* grad, float cx, float cy, float radius);
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
1251 TVG_EXPORT Tvg_Result tvg_radial_gradient_get(Tvg_Gradient* grad, float* cx, float* cy, float* radius);
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
1264 TVG_EXPORT Tvg_Result tvg_gradient_set_color_stops(Tvg_Gradient* grad, const Tvg_Color_Stop* color_stop, uint32_t cnt);
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
1277 TVG_EXPORT Tvg_Result tvg_gradient_get_color_stops(Tvg_Gradient* grad, const Tvg_Color_Stop** color_stop, uint32_t* cnt);
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
1289 TVG_EXPORT Tvg_Result tvg_gradient_set_spread(Tvg_Gradient* grad, const Tvg_Stroke_Fill spread);
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
1301 TVG_EXPORT Tvg_Result tvg_gradient_get_spread(Tvg_Gradient* grad, Tvg_Stroke_Fill* spread);
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
1312 TVG_EXPORT Tvg_Result tvg_gradient_del(Tvg_Gradient* grad);
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.
1326 /************************************************************************/
1328 /************************************************************************/
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
1336 TVG_EXPORT Tvg_Paint* tvg_picture_new();
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
1348 TVG_EXPORT Tvg_Result tvg_picture_load(Tvg_Paint* paint, const char* path);
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
1363 TVG_EXPORT Tvg_Result tvg_picture_load_raw(Tvg_Paint* paint, uint32_t *data, uint32_t w, uint32_t h, bool copy);
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
1378 TVG_EXPORT Tvg_Result tvg_picture_get_viewbox(const Tvg_Paint* paint, float* x, float* y, float* w, float* h);
1383 * \defgroup ThorVGCapi_Scene Scene
1384 * \brief Functions enabling to hold many Paint objects.
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.
1392 /************************************************************************/
1394 /************************************************************************/
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
1401 TVG_EXPORT Tvg_Paint* tvg_scene_new();
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
1414 TVG_EXPORT Tvg_Result tvg_scene_reserve(Tvg_Paint* scene, uint32_t size);
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
1427 TVG_EXPORT Tvg_Result tvg_scene_push(Tvg_Paint* scene, Tvg_Paint* paint);
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
1439 TVG_EXPORT Tvg_Result tvg_scene_clear(Tvg_Paint* scene);
1448 #endif //_THORVG_CAPI_H_