*
* 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
*
* 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.
*
* @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;
* @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;
*
* @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.
*/
/**
* @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.
*/
/**
* @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.
/**
* @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.
*
* @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
*/
* - 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
*
*/
*
* 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.
*
* 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.
*
* 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.
* \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.
*/
*
* \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
*
* \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);
* \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.
* 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);
*
* \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);
* \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);
* \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);
*
* \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);
/**
* \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.
*
*
* \{
* \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.
*/
*
* \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);
/*!
* \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()
projects / platform / core / graphics / tizenvg.git / commitdiff