From 9ceba0982f6ee1bf60794e9f5ab42b0f1b507df8 Mon Sep 17 00:00:00 2001 From: JunsuChoi Date: Thu, 29 Apr 2021 14:21:07 +0900 Subject: [PATCH] doc common: Groupping c APIs C APIs - Initializer - Canvas - SwCanvas - Paint - Shape - Gradient - Picture - Scene --- inc/thorvg_capi.h | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 137 insertions(+), 3 deletions(-) diff --git a/inc/thorvg_capi.h b/inc/thorvg_capi.h index fce9c43..155e84e 100644 --- a/inc/thorvg_capi.h +++ b/inc/thorvg_capi.h @@ -39,33 +39,50 @@ typedef struct _Tvg_Paint Tvg_Paint; typedef struct _Tvg_Gradient Tvg_Gradient; /** - * \defgroup ThorVGCapi C APIs - */ +* \defgroup ThorVGCapi C APIs +* \brief ThorVG provides C interface. +* +* \{ +*/ -/**@{*/ +/** +* \defgroup ThorVGCapi_Initializer Initializer +* \brief Enables initialization and termination of the ThorVG engine. +* +* \{ +*/ /*! * \def TVG_ENGINE_SW * Software raster engine type. */ #define TVG_ENGINE_SW (1 << 1) + + /*! * \def TVG_ENGINE_GL * GL raster engine type. */ #define TVG_ENGINE_GL (1 << 2) +/*\}*/ + /*! +* \ingroup ThorVGCapi_Canvas * \def TVG_COLORSPACE_ABGR8888 * Colorspace used to fill buffer. */ #define TVG_COLORSPACE_ABGR8888 0 + + /*! +* \ingroup ThorVGCapi_Canvas * \def TVG_COLORSPACE_ARGB8888 * Colorspace used to fill buffer. */ #define TVG_COLORSPACE_ARGB8888 1 + typedef enum { TVG_RESULT_SUCCESS = 0, TVG_RESULT_INVALID_ARGUMENT, @@ -111,6 +128,7 @@ typedef enum { TVG_FILL_RULE_EVEN_ODD } Tvg_Fill_Rule; + typedef enum { TVG_COMPOSITE_METHOD_NONE = 0, TVG_COMPOSITE_METHOD_CLIP_PATH, @@ -118,6 +136,7 @@ typedef enum { TVG_COMPOSITE_METHOD_INVERSE_ALPHA_MASK, } Tvg_Composite_Method; + typedef struct { float x, y; @@ -146,6 +165,7 @@ typedef struct * \fn Tvg_Result tvg_engine_init(unsigned engine_method, unsigned threads) * \brief The funciton initialises thorvg library. It must be called before the * other functions at the beggining of thorvg client. +* \ingroup ThorVGCapi_Initializer Initializer * \code * tvg_engine_init(TVG_ENGINE_SW, 0); //Initialize software renderer and use 1 thread * \endcode @@ -169,6 +189,7 @@ TVG_EXPORT Tvg_Result tvg_engine_init(unsigned engine_method, unsigned threads); * \brief The funciton termiates renderer tasks. Used for cleanup. * It should be called in case of termination of the thorvg library with same * renderer types as it was passed in tvg_engine_init() +* \ingroup ThorVGCapi_Initializer Initializer * \code * tvg_engine_init(TVG_ENGINE_SW, 0); * //define canvas and shapes, update shapes, general rendering calls @@ -187,6 +208,22 @@ TVG_EXPORT Tvg_Result tvg_engine_init(unsigned engine_method, unsigned threads); TVG_EXPORT Tvg_Result tvg_engine_term(unsigned engine_method); +/** +* \defgroup ThorVGCapi_Canvas Canvas +* \brief Functions for drawing graphic elements. +* It stores all Paint objects (Shape, Scene, Picture) and creates the buffer, which can be drawn on the screen. +* +* \{ +*/ + +/** +* \defgroup ThorVGCapi_SwCanvas SwCanvas +* \ingroup ThorVGCapi_Canvas +* \brief Functions for the rasterisation of graphic elements with a software engine. +* +* \{ +*/ + /************************************************************************/ /* SwCanvas API */ /************************************************************************/ @@ -238,6 +275,9 @@ TVG_EXPORT Tvg_Canvas* tvg_swcanvas_create(); 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); +/* \} */ + + /************************************************************************/ /* Common Canvas API */ /************************************************************************/ @@ -452,6 +492,15 @@ TVG_EXPORT Tvg_Result tvg_canvas_draw(Tvg_Canvas* canvas); */ TVG_EXPORT Tvg_Result tvg_canvas_sync(Tvg_Canvas* canvas); +/* \} */ + +/** +* \defgroup ThorVGCapi_Paint Paint +* \brief Functions for managing graphic elements. It enables duplication, transformation and composition. +* +* \{ +*/ + /************************************************************************/ /* Paint API */ /************************************************************************/ @@ -597,6 +646,18 @@ TVG_EXPORT Tvg_Result tvg_paint_get_bounds(const Tvg_Paint* paint, float* x, flo */ TVG_EXPORT Tvg_Result tvg_paint_set_composite_method(Tvg_Paint* paint, Tvg_Paint* target, Tvg_Composite_Method method); +/** \}*/ + +/** +* \defgroup ThorVGCapi_Shape Shape +* \brief Functions representing two-dimensional figures and their properties. +* The shapes of the figures in the Shape object are stored as the sub-paths in the path. +* The data to be saved in the path can be read directly from the svg file or through the provided APIs. +* +* \{ +*/ + + /************************************************************************/ /* Shape API */ /************************************************************************/ @@ -837,8 +898,41 @@ TVG_EXPORT Tvg_Result tvg_shape_set_stroke_color(Tvg_Paint* paint, uint8_t r, ui */ 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); + +/*! +* \fn TVG_EXPORT Tvg_Result tvg_shape_set_stroke_linear_gradient(Tvg_Paint* paint, Tvg_Gradient* grad) +* \brief The function inserts linear gradient object as an shape stroke. +* \param[in] paint Tvg_Paint pointer +* \param[in] grad Tvg_Gradient pointer (linear) +* \return Tvg_Result return value +* - TVG_RESULT_SUCCESS: if ok. +* - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid +*/ TVG_EXPORT Tvg_Result tvg_shape_set_stroke_linear_gradient(Tvg_Paint* paint, Tvg_Gradient* grad); + + +/*! +* \fn TVG_EXPORT Tvg_Result tvg_shape_set_stroke_radial_gradient(Tvg_Paint* paint, Tvg_Gradient* grad) +* \brief The function inserts radial gradient object as an shape stroke. +* \param[in] paint Tvg_Paint pointer +* \param[in] grad Tvg_Gradient pointer +* \return Tvg_Result return value +* - TVG_RESULT_SUCCESS: if ok. +* - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid +*/ TVG_EXPORT Tvg_Result tvg_shape_set_stroke_radial_gradient(Tvg_Paint* paint, Tvg_Gradient* grad); + + +/*! +* \fn TVG_EXPORT Tvg_Result tvg_shape_get_stroke_gradient(const Tvg_Paint* paint, Tvg_Gradient** grad) +* \brief The function returns gradient previously inserted to given shape stroke. Function deos not +* allocate any data. +* \param[in] paint Tvg_Paint pointer +* \param[out] grad Tvg_Gradient pointer +* \return Tvg_Result return value +* - TVG_RESULT_SUCCESS: if ok. +* - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid +*/ TVG_EXPORT Tvg_Result tvg_shape_get_stroke_gradient(const Tvg_Paint* paint, Tvg_Gradient** grad); @@ -1035,6 +1129,21 @@ TVG_EXPORT Tvg_Result tvg_shape_set_radial_gradient(Tvg_Paint* paint, Tvg_Gradie */ TVG_EXPORT Tvg_Result tvg_shape_get_gradient(const Tvg_Paint* paint, Tvg_Gradient** grad); +/** \}*/ + +/** +* \defgroup ThorVGCapi_Gradient Gradient +* \brief Functions representing the gradient fill of the Shape object. +* +* It contains the information about the gradient colors and their arrangement +* inside the gradient bounds. The gradients bounds are defined in the LinearGradient +* or RadialGradient class, depending on the type of the gradient to be used. +* It specifies the gradient behavior in case the area defined by the gradient bounds +* is smaller than the area to be filled. +* +* \{ +*/ + /************************************************************************/ /* Gradient API */ /************************************************************************/ @@ -1202,6 +1311,18 @@ TVG_EXPORT Tvg_Result tvg_gradient_get_spread(Tvg_Gradient* grad, Tvg_Stroke_Fil */ TVG_EXPORT Tvg_Result tvg_gradient_del(Tvg_Gradient* grad); +/** \}*/ + +/** +* \defgroup ThorVGCapi_Picture Picture +* \brief Functions class representing an image read in one of the supported formats: svg, png and raw. +* Besides the methods inherited from the Paint, it provides methods to load the image, +* to change its size and to get the basic information. +* +* \{ +*/ + + /************************************************************************/ /* Picture API */ /************************************************************************/ @@ -1256,6 +1377,18 @@ TVG_EXPORT Tvg_Result tvg_picture_load_raw(Tvg_Paint* paint, uint32_t *data, uin */ TVG_EXPORT Tvg_Result tvg_picture_get_viewbox(const Tvg_Paint* paint, float* x, float* y, float* w, float* h); +/** \}*/ + +/** +* \defgroup ThorVGCapi_Scene Scene +* \brief Functions enabling to hold many Paint objects. +* +* As a whole they can be transformed, their transparency can be changed, or the composition +* methods may be used to all of them at once. +* +* \{ +*/ + /************************************************************************/ /* Scene API */ /************************************************************************/ @@ -1304,6 +1437,7 @@ TVG_EXPORT Tvg_Result tvg_scene_push(Tvg_Paint* scene, Tvg_Paint* paint); * - TVG_RESULT_INVALID_PARAMETERS: if paint is invalid */ TVG_EXPORT Tvg_Result tvg_scene_clear(Tvg_Paint* scene); +/** \}*/ /** \}*/ -- 2.7.4