From dc55070ba7284352784f16c0f3a6ef1623113e21 Mon Sep 17 00:00:00 2001 From: Mira Grudzinska Date: Mon, 4 Oct 2021 02:12:37 +0200 Subject: [PATCH] docs: c and c++ apis docs improved --- inc/thorvg.h | 24 +++++------ src/bindings/capi/thorvg_capi.h | 71 ++++++++++++++++++--------------- 2 files changed, 50 insertions(+), 45 deletions(-) diff --git a/inc/thorvg.h b/inc/thorvg.h index 8905ba40..3da67e63 100644 --- a/inc/thorvg.h +++ b/inc/thorvg.h @@ -3,7 +3,7 @@ * * The main APIs enabling the TVG initialization, preparation of the canvas and provisioning of its content: * - drawing shapes such as line, curve, arc, rectangle, circle or user-defined - * - drawing pictures - SVG, PNG, RAW + * - drawing pictures - SVG, PNG, JPG, RAW * - solid or gradient filling * - continuous and dashed stroking * - clipping and masking @@ -455,7 +455,7 @@ public: * * Only pushed paints in the canvas will be drawing targets. * They are retained by the canvas until you call Canvas::clear(). - * If you know the number of the pushed objects in the advance, please call Canvas::reserve(). + * If you know the number of the pushed objects in advance, please call Canvas::reserve(). * * @param[in] paint A Paint object to be drawn. * @@ -545,7 +545,9 @@ public: * @param[in] x2 The horizontal coordinate of the second point used to determine the gradient bounds. * @param[in] y2 The vertical coordinate of the second point used to determine the gradient bounds. * - * @return Result::Success when succeed, Result::InvalidArguments otherwise. + * @return Result::Success when succeed. + * + * @note In case the first and the second points are equal, an object filled with such a gradient fill is not rendered. */ Result linear(float x1, float y1, float x2, float y2) noexcept; @@ -596,7 +598,7 @@ public: * @param[in] cy The vertical coordinate of the center of the bounding circle. * @param[in] radius The radius of the bounding circle. * - * @return Result::Success when succeed, Result::InvalidArguments otherwise. + * @return Result::Success when succeed, Result::InvalidArguments in case the @p radius value is zero or less. */ Result radial(float cx, float cy, float radius) noexcept; @@ -829,9 +831,8 @@ public: * * @retval Result::Success When succeed. * @retval Result::FailedAllocation An internal error with a memory allocation for an object to be dashed. - * @retval Result::InvalidArguments In case that either @p dashPattern is @c nullptr or @p cnt is zero. + * @retval Result::InvalidArguments In case @p dashPattern is @c nullptr and @p cnt > 0, @p cnt is zero, any of the dash pattern values is zero or less. * - * @note If any of the dash pattern values is zero, this function has no effect. * @note To reset the stroke dash pattern, pass @c nullptr to @p dashPattern and zero to @p cnt. * @warning @p cnt must be greater than 1 if the dash pattern is valid. */ @@ -889,7 +890,7 @@ public: /** * @brief Sets the fill rule for the Shape object. * - * @param[in] r The fill rule value. + * @param[in] r The fill rule value. The default value is @c FillRule::Winding. * * @return Result::Success when succeed. */ @@ -1002,7 +1003,7 @@ public: /** * @class Picture * - * @brief A class representing an image read in one of the supported formats: raw, svg, png and etc. + * @brief A class representing an image read in one of the supported formats: raw, svg, png, jpg and etc. * Besides the methods inherited from the Paint, it provides methods to load & draw images on the canvas. * * @note Supported formats are depended on the available TVG loaders. @@ -1144,9 +1145,9 @@ public: /** * @brief Passes drawing elements to the Scene using Paint objects. * - * Only pushed paints in the scene will be drawing targets. - * They are retained by the scene until you call Scene::clear(). - * If you know the number of the pushed objects in the advance, please call Scene::reserve(). + * Only the paints pushed into the scene will be the drawn targets. + * The paints are retained by the scene until Scene::clear() is called. + * If you know the number of the pushed objects in advance, please call Scene::reserve(). * * @param[in] paint A Paint object to be drawn. * @@ -1178,7 +1179,6 @@ public: * @return Result::Success when succeed * * @warning If you don't free the paints they become dangled. They are supposed to be reused, otherwise you are responsible for their lives. Thus please use the @p free argument only when you know how it works, otherwise it's not recommended. - * @warning Please do not use it, this API is not official one. It could be modified in the next version. * * @since 0.2 */ diff --git a/src/bindings/capi/thorvg_capi.h b/src/bindings/capi/thorvg_capi.h index bea99db4..6fadf186 100644 --- a/src/bindings/capi/thorvg_capi.h +++ b/src/bindings/capi/thorvg_capi.h @@ -11,7 +11,7 @@ * - scene graph & affine transformation (translation, rotation, scale, ...) * - stroking: width, join, cap, dash * - composition: blending, masking, path clipping -* - pictures: SVG, PNG, bitmap +* - pictures: SVG, PNG, JPG, bitmap * */ @@ -460,7 +460,7 @@ TVG_EXPORT Tvg_Result tvg_canvas_destroy(Tvg_Canvas* canvas); * * Only the paints pushed into the canvas will be drawing targets. * They are retained by the canvas until you call tvg_canvas_clear(). -* If you know the number of the pushed objects in the advance, please call tvg_canvas_reserve(). +* If you know the number of the pushed objects in advance, please call tvg_canvas_reserve(). * * \return Tvg_Result return values: * \retval TVG_RESULT_SUCCESS Succeed. @@ -1077,7 +1077,7 @@ TVG_EXPORT Tvg_Result tvg_shape_append_path(Tvg_Paint* paint, const Tvg_Path_Com * * tvg_shape_append_circle(shape, 10, 10, 50, 50); * tvg_shape_get_path_coords(shape, (const Tvg_Point**)&coords, &len); -* //TVG approximates a circle by four Bezier lines. In the example above the cmds array stores their coordinates +* //TVG approximates a circle by four Bezier curves. In the example above the coords array stores their coordinates. * \endcode * * \param[in] paint A Tvg_Paint pointer to the shape object. @@ -1103,7 +1103,7 @@ TVG_EXPORT Tvg_Result tvg_shape_get_path_coords(const Tvg_Paint* paint, const Tv * * tvg_shape_append_circle(shape, 10, 10, 50, 50); * tvg_shape_get_path_commands(shape, (const Tvg_Path_Command**)&cmds, &len); -* //TVG approximates a circle by four Bezier lines. In the example above the cmds array stores their coordinates +* //TVG approximates a circle by four Bezier curves. In the example above the cmds array stores the commands of the path data. * \endcode * * \param[in] paint A Tvg_Paint pointer to the shape object. @@ -1156,7 +1156,7 @@ TVG_EXPORT Tvg_Result tvg_shape_get_stroke_width(const Tvg_Paint* paint, float* * \return Tvg_Result enumeration. * \retval TVG_RESULT_SUCCESS Succeed. * \retval TVG_RESULT_INVALID_ARGUMENT An invalid Tvg_Paint pointer. -* \retval TVG_RESULT_INSUFFICIENT_CONDITION An internal error with a memory allocation. +* \retval TVG_RESULT_FAILED_ALLOCATION An internal error with a memory allocation. * * \note Either a solid color or a gradient fill is applied, depending on what was set as last. */ @@ -1234,7 +1234,7 @@ TVG_EXPORT Tvg_Result tvg_shape_get_stroke_gradient(const Tvg_Paint* paint, Tvg_ * * \code * //dash pattern examples -* float dashPattern[2] = {20, 10}; // -- - -- - -- - +* float dashPattern[2] = {20, 10}; // -- -- -- * float dashPattern[2] = {40, 20}; // ---- ---- ---- * float dashPattern[4] = {10, 20, 30, 40} // - --- - --- * \endcode @@ -1245,8 +1245,10 @@ TVG_EXPORT Tvg_Result tvg_shape_get_stroke_gradient(const Tvg_Paint* paint, Tvg_ * * \return Tvg_Result enumeration. * \retval TVG_RESULT_SUCCESS Succeed. -* \retval TVG_RESULT_INVALID_ARGUMENT An invalid pointer passed as an argument, the given length of the array is less than two or any of the @p dashPattern values is zero or less. +* \retval TVG_RESULT_INVALID_ARGUMENT An invalid pointer passed as an argument and @p cnt > 0, the given length of the array is less than two or any of the @p dashPattern values is zero or less. * \retval TVG_RESULT_FAILED_ALLOCATION An internal error with a memory allocation. +* +* \note To reset the stroke dash pattern, pass @c nullptr to @p dashPattern and zero to @p cnt. */ TVG_EXPORT Tvg_Result tvg_shape_set_stroke_dash(Tvg_Paint* paint, const float* dashPattern, uint32_t cnt); @@ -1300,7 +1302,7 @@ TVG_EXPORT Tvg_Result tvg_shape_get_stroke_cap(const Tvg_Paint* paint, Tvg_Strok * \brief Sets the join style for stroked path segments. * * \param[in] paint A Tvg_Paint pointer to the shape object. -* \param[in] join The join style value. The default value is @c TVG_STROKE_JOIN_BEVEL . +* \param[in] join The join style value. The default value is @c TVG_STROKE_JOIN_BEVEL. * * \return Tvg_Result enumeration. * \retval TVG_RESULT_SUCCESS Succeed. @@ -1396,10 +1398,10 @@ TVG_EXPORT Tvg_Result tvg_shape_get_fill_rule(const Tvg_Paint* paint, Tvg_Fill_R * tvg_linear_gradient_set(grad, 700, 700, 800, 800); * Tvg_Color_Stop color_stops[4] = * { -* {.offset=0.0, .r=0, .g=0, .b=0, .a=255}, -* {.offset=0.25, .r=255, .g=0, .b=0, .a=255}, -* {.offset=0.5, .r=0, .g=255, .b=0, .a=255}, -* {.offset=1.0, .r=0, .g=0, .b=255, .a=255} +* {0.0 , 0, 0, 0, 255}, +* {0.25, 255, 0, 0, 255}, +* {0.5 , 0, 255, 0, 255}, +* {1.0 , 0, 0, 255, 255} * }; * tvg_gradient_set_color_stops(grad, color_stops, 4); * tvg_shape_set_linear_gradient(shape, grad); @@ -1426,13 +1428,13 @@ TVG_EXPORT Tvg_Result tvg_shape_set_linear_gradient(Tvg_Paint* paint, Tvg_Gradie * * \code * Tvg_Gradient* grad = tvg_radial_gradient_new(); -* tvg_radial_gradient_set(grad, 550, 550, 50)); +* tvg_radial_gradient_set(grad, 550, 550, 50); * Tvg_Color_Stop color_stops[4] = * { -* {.offset=0.0, .r=0, .g=0, .b=0, .a=255}, -* {.offset=0.25, .r=255, .g=0, .b=0, .a=255}, -* {.offset=0.5, .r=0, .g=255, .b=0, .a=255}, -* {.offset=1.0, .r=0, .g=0, .b=255, .a=255} +* {0.0 , 0, 0, 0, 255}, +* {0.25, 255, 0, 0, 255}, +* {0.5 , 0, 255, 0, 255}, +* {1.0 , 0, 0, 255, 255} * }; * tvg_gradient_set_color_stops(grad, color_stops, 4); * tvg_shape_set_radial_gradient(shape, grad); @@ -1488,14 +1490,14 @@ TVG_EXPORT Tvg_Result tvg_shape_get_gradient(const Tvg_Paint* paint, Tvg_Gradien * \brief Creates a new linear gradient object. * * \code -* Tvg_Paint shape = tvg_shape_new(); +* Tvg_Paint* shape = tvg_shape_new(); * tvg_shape_append_rect(shape, 700, 700, 100, 100, 20, 20); * Tvg_Gradient* grad = tvg_linear_gradient_new(); * tvg_linear_gradient_set(grad, 700, 700, 800, 800); * Tvg_Color_Stop color_stops[2] = * { -* {.offset=0, .r=0, .g=0, .b=0, .a=255}, -* {.offset=1, .r=0, .g=255, .b=0, .a=255}, +* {0.0, 0, 0, 0, 255}, +* {1.0, 0, 255, 0, 255}, * }; * tvg_gradient_set_color_stops(grad, color_stops, 2); * tvg_shape_set_linear_gradient(shape, grad); @@ -1510,14 +1512,14 @@ TVG_EXPORT Tvg_Gradient* tvg_linear_gradient_new(); * \brief Creates a new radial gradient object. * * \code -* Tvg_Paint shape = tvg_shape_new(); +* Tvg_Paint* shape = tvg_shape_new(); * tvg_shape_append_rect(shape, 700, 700, 100, 100, 20, 20); * Tvg_Gradient* grad = tvg_radial_gradient_new(); -* tvg_linear_gradient_set(grad, 550, 550, 50); +* tvg_radial_gradient_set(grad, 550, 550, 50); * Tvg_Color_Stop color_stops[2] = * { -* {.offset=0, .r=0, .g=0, .b=0, .a=255}, -* {.offset=1, .r=0, .g=255, .b=0, .a=255}, +* {0.0, 0, 0, 0, 255}, +* {1.0, 0, 255, 0, 255}, * }; * tvg_gradient_set_color_stops(grad, color_stops, 2); * tvg_shape_set_radial_gradient(shape, grad); @@ -1543,7 +1545,9 @@ TVG_EXPORT Tvg_Gradient* tvg_radial_gradient_new(); * * \return Tvg_Result enumeration. * \retval TVG_RESULT_SUCCESS Succeed. -* \retval TVG_RESULT_INVALID_ARGUMENT An invalid Tvg_Gradient pointer or the first and the second points are equal. +* \retval TVG_RESULT_INVALID_ARGUMENT An invalid Tvg_Gradient pointer. +* +* \note In case the first and the second points are equal, an object filled with such a gradient fill is not rendered. */ TVG_EXPORT Tvg_Result tvg_linear_gradient_set(Tvg_Gradient* grad, float x1, float y1, float x2, float y2); @@ -1674,7 +1678,7 @@ TVG_EXPORT Tvg_Result tvg_gradient_del(Tvg_Gradient* grad); /** * \defgroup ThorVGCapi_Picture Picture * -* \brief A module enabling to create and to load an image in one of the supported formats: svg, png and raw. +* \brief A module enabling to create and to load an image in one of the supported formats: svg, png, jpg and raw. * * * \{ @@ -1710,8 +1714,8 @@ TVG_EXPORT Tvg_Result tvg_picture_load(Tvg_Paint* paint, const char* path); * \brief Loads a picture data from a memory block of a given size. (BETA_API) * * \return Tvg_Result return value -* \retval TVG_RESULT_SUCCESS: if ok. -* \retval TVG_RESULT_INVALID_PARAMETERS: if paint is invalid +* \retval TVG_RESULT_SUCCESS Succeed. +* \retval TVG_RESULT_INVALID_PARAMETERS: An invalid Tvg_Paint. * * \warning Please do not use it, this API is not official one. It can be modified in the next version. */ @@ -1813,6 +1817,7 @@ TVG_EXPORT Tvg_Paint* tvg_scene_new(); * * \return Tvg_Result enumeration. * \retval TVG_RESULT_SUCCESS Succeed. +* \retval TVG_RESULT_FAILED_ALLOCATION An internal error with a memory allocation. * \retval TVG_RESULT_INVALID_ARGUMENT An invalid Tvg_Paint pointer. */ TVG_EXPORT Tvg_Result tvg_scene_reserve(Tvg_Paint* scene, uint32_t size); @@ -1821,17 +1826,17 @@ TVG_EXPORT Tvg_Result tvg_scene_reserve(Tvg_Paint* scene, uint32_t size); /*! * \brief Passes drawing elements to the scene using Tvg_Paint objects. * -* Only the paints pushed into the scene will be drawing targets. -* If you know the number of pushed objects in the advance, please call tvg_scene_reserve(). +* Only the paints pushed into the scene will be the drawn targets. +* The paints are retained by the scene until the tvg_scene_clear() is called. +* If you know the number of pushed objects in advance, please call tvg_scene_reserve(). * * \param[in] scene A Tvg_Paint pointer to the scene object. * \param[in] paint A graphical object to be drawn. * * \return Tvg_Result enumeration. * \retval TVG_RESULT_SUCCESS Succeed. -* \retval TVG_RESULT_INVALID_ARGUMENT An invalid pointer to the @p scene. -* \retval TVG_RESULT_MEMORY_CORRUPTION An invalid pointer to the @p paint. -* \retval TVG_RESULT_INSUFFICIENT_CONDITION An internal error. +* \retval TVG_RESULT_INVALID_ARGUMENT A @c nullptr passed as the argument. +* \retval TVG_RESULT_MEMORY_CORRUPTION An internal error. * * \note The rendering order of the paints is the same as the order as they were pushed. Consider sorting the paints before pushing them if you intend to use layering. * \see tvg_scene_reserve()