From 4fd1832990ae002eaecc4efc4e425fca03e225cb Mon Sep 17 00:00:00 2001 From: JunsuChoi Date: Tue, 27 Apr 2021 11:21:16 +0900 Subject: [PATCH 01/16] doc common: Fix typo and missing parameter --- inc/thorvg.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/inc/thorvg.h b/inc/thorvg.h index 810266c..557dd3b 100644 --- a/inc/thorvg.h +++ b/inc/thorvg.h @@ -514,7 +514,7 @@ public: * Corresponds to the M command from the svg path commands. * * @param[in] x The horizontal coordinate of the initial point of the sub-path. - * @param[in] t The vertical coordinate of the initial point of the sub-path. + * @param[in] y The vertical coordinate of the initial point of the sub-path. * @return Result::Success. */ Result moveTo(float x, float y) noexcept; @@ -528,7 +528,7 @@ public: * In case this is the first command in the path, it corresponds to the moveTo command. * * @param[in] x The horizontal coordinate of the endpoint of the line. - * @param[in] t The vertical coordinate of the endpoint of the line. + * @param[in] y The vertical coordinate of the endpoint of the line. * @return Result::Success. */ Result lineTo(float x, float y) noexcept; @@ -547,7 +547,7 @@ public: * @param[in] cx2 The horizontal coordinate of the 2nd control point. * @param[in] cy2 The vertical coordinate of the 2nd control point. * @param[in] x The horizontal coordinate of the endpoint of the curve. - * @param[in] t The vertical coordinate of the endpoint of the curve. + * @param[in] y The vertical coordinate of the endpoint of the curve. * @return Result::Success. */ Result cubicTo(float cx1, float cy1, float cx2, float cy2, float x, float y) noexcept; @@ -666,7 +666,7 @@ public: /** * @brief Sets the gradient fill of the stroke for all of the figures from the path.. - * @param[in] The unique pointer to the gradient fill. + * @param[in] f The unique pointer to the gradient fill. * @return Result::Success when succeeded, Result::FailedAllocation or Result::MemoryCorruption otherwise. */ Result stroke(std::unique_ptr f) noexcept; @@ -715,7 +715,7 @@ public: * * The parts of the shape defined as inner are filled. * - * @param[in] The unique pointer to the gradient fill. + * @param[in] f The unique pointer to the gradient fill. * @return Result::Success when succeeded, Result::MemoryCorruption otherwise. */ Result fill(std::unique_ptr f) noexcept; -- 2.7.4 From 2707f8ce8ee202c426b10fd35a819482298191ad Mon Sep 17 00:00:00 2001 From: Hermet Park Date: Wed, 28 Apr 2021 13:40:14 +0900 Subject: [PATCH 02/16] bump up v0.1.3 Change-Id: If6c037defcf1c240797ae315614aad89dad365a6 --- packaging/thorvg.spec | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packaging/thorvg.spec b/packaging/thorvg.spec index 171cbec..792e13b 100644 --- a/packaging/thorvg.spec +++ b/packaging/thorvg.spec @@ -1,6 +1,6 @@ Name: thorvg Summary: Thor Vector Graphics Library -Version: 0.1.2 +Version: 0.1.3 Release: 1 Group: Graphics System/Rendering Engine License: MIT -- 2.7.4 From 45f6a847f7bf4d4205606e401d6562de6772a702 Mon Sep 17 00:00:00 2001 From: JunsuChoi Date: Tue, 27 Apr 2021 09:39:03 +0900 Subject: [PATCH 03/16] doc README: Update build status badge The badge provided by travis-ci is no longer used. Use the badge provided by github action. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4e23a37..3b8f787 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![Build Status](https://travis-ci.org/Samsung/thorvg.svg?branch=master)](https://travis-ci.org/Samsung/thorvg) +[![Continuous-integration](https://github.com/Samsung/thorvg/actions/workflows/actions.yml/badge.svg)](https://github.com/Samsung/thorvg/actions/workflows/actions.yml) [![Gitter](https://badges.gitter.im/thorvg/community.svg)](https://gitter.im/thorvg/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) # ThorVG -- 2.7.4 From 0238775bebb93c530958944b69c71040d7aebedc Mon Sep 17 00:00:00 2001 From: Mira Grudzinska Date: Mon, 26 Apr 2021 21:18:44 +0200 Subject: [PATCH 04/16] doc common: adding the documentation for the C++ APIs Added the missing descriptions for Sw/Gl/Canvas and Initializer. @retval command applied. --- inc/thorvg.h | 187 ++++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 116 insertions(+), 71 deletions(-) diff --git a/inc/thorvg.h b/inc/thorvg.h index 557dd3b..98761b3 100644 --- a/inc/thorvg.h +++ b/inc/thorvg.h @@ -1,5 +1,5 @@ /*! -* \file thorvg.h +* @file thorvg.h */ @@ -67,7 +67,8 @@ enum class TVG_EXPORT Result /** * @brief Enumeration specifying the values of the path commands accepted by ThorVG. * - * Not to be confused with the path commands from the svg path element. + * Not to be confused with the path commands from the svg path element (like M, L, Q, H and many others). + * ThorVG interprets all of them and translates to the ones from the PathCommand values. */ enum class TVG_EXPORT PathCommand { @@ -162,7 +163,9 @@ struct Matrix * * @ingroup ThorVG * - * @brief A class for drawing a vector primitive. + * @brief A class for managing graphic elements. + * + * It enables duplication, transformation and composition. * */ class TVG_EXPORT Paint @@ -332,8 +335,9 @@ public: * * @ingroup ThorVG * - * @brief CanvasView is a class for displaying an vector primitives. + * @brief A class for drawing graphic elements. * + * It stores all Paint objects (Shape, Scene, Picture) and creates the buffer, which can be drawn on the screen. */ class TVG_EXPORT Canvas { @@ -341,35 +345,63 @@ public: Canvas(RenderMethod*); virtual ~Canvas(); + /** + * @brief Sets the size of the container, where all the paints pushed into the scene are stored. + * + * If the number of objects pushed into the Canvas is known in advance, calling the function + * prevents multiple memory reallocation, thus improving the performance. + * + * @param[in] n The number of objects for which the memory is to be reserved. + * @return Result::Success. + */ Result reserve(uint32_t n) noexcept; + /** - * @brief Add paint object to the canvas - * This method is similar to registration. The added paint is drawn on the inner canvas. - * return + * @brief Passes the Paint object to the Canvas. + * + * The function may be called many times and all passed objects will be rendered. + * Calling it initializes the data preparation of the chosen engine type. + * + * @param[in] paint A unique pointer to the Paint object. + * @retval Result::Success When succeeded. + * @retval Result::MemoryCorruption In case a @c nullptr is passed as the argument. + * @retval Result::InsufficientCondition An internal error. */ virtual Result push(std::unique_ptr paint) noexcept; /** - * @brief - * @param[in] + * @brief Sets the total number of the paints pushed into the scene to be zero. + * Depending on the value of the given argument, the memory is free or not. + * + * @param[in] free If @c then true the memory occupied by paints is deallocated, otherwise it is not. * return Result::Success when succeeded, Result::InsufficientCondition otherwise. */ virtual Result clear(bool free = true) noexcept; /** - * @brief ... - * @param[in] - * return + * @brief Updates the chosen Paint object or all objects from the Canvas object. + * + * If a @c nullptr is passed all objects from the Canvas are updated. + * Otherwise only the paint to which the given argument points. + * + * @param[in] paint A pointer to the Paint object or @c nullptr. + * return Result::Success when succeeded, Result::InsufficientCondition otherwise. */ virtual Result update(Paint* paint) noexcept; /** - * @brief Draw target buffer added to the canvas. + * @brief Draws all objects from the Canvas object. + * return Result::Success when succeeded, Result::InsufficientCondition otherwise. */ virtual Result draw() noexcept; /** - * @brief ... + * @brief Guaranties that all Paint objects from the Canvas object are already rendered. + * + * The Canvas components can be rendered asynchronously. To make sure, that all of them + * are ready, the sync API should be called after the draw API. + * + * return Result::Success when succeeded, Result::InsufficientCondition otherwise. */ virtual Result sync() noexcept; @@ -481,7 +513,6 @@ public: }; - /** * @class Shape * @@ -666,8 +697,10 @@ public: /** * @brief Sets the gradient fill of the stroke for all of the figures from the path.. - * @param[in] f The unique pointer to the gradient fill. - * @return Result::Success when succeeded, Result::FailedAllocation or Result::MemoryCorruption otherwise. + * @param[in] The unique pointer to the gradient fill. + * @retval Result::Success When succeeded. + * @retval Result::FailedAllocation An internal error with a memory allocation for an object to be filled. + * @retval Result::MemoryCorruption In case a @c nullptr is passed as the argument. */ Result stroke(std::unique_ptr f) noexcept; @@ -678,7 +711,10 @@ public: * * @param[in] dashPattern The array of consecutive pair values of the dash length and the gap length. * @param[in] cnt The length of the @p dashPattern array. - * @return Result::Success when succeeded, Result::FailedAllocation or Result::InvalidArguments otherwise. + * @retval Result::Success When succeeded. + * @retval Result::FailedAllocation An internal error with a memory allocation for an object to be dashed. + * @retval Result::InvalidArguments In case a @c nullptr is passed as the @p dashPattern, + * the given length of the array is less than two or any of the @p dashPattern values is zero or less. */ Result stroke(const float* dashPattern, uint32_t cnt) noexcept; @@ -835,10 +871,10 @@ public: * The direct loading from a file is available for the svg and png files. * * @param[in] path A path to the picture file. - * @return Result::Success when succeeded, otherwise the returned value depends on the problem type: - * Result::InvalidArguments - in case the @p path is empty, - * Result::NonSupport - when trying to load a file with an unknown extension, - * Result::Unknown - if an error occurs at a later stage. + * @retval Result::Success When succeeded. + * @retval Result::InvalidArguments In case the @p path is empty. + * @retval Result::NonSupport When trying to load a file with an unknown extension. + * @retval Result::Unknown If an error occurs at a later stage. */ Result load(const std::string& path) noexcept; @@ -849,10 +885,10 @@ public: * * @param[in] data A pointer to a memory location where the content of the svg file is stored. * @param[in] size The size in bytes of the memory occupied by the @p data. - * @return Result::Success when succeeded, otherwise the returned value depends on the problem type: - * Result::InvalidArguments - in case no data are provided or the @p size is zero or less, - * Result::NonSupport - when trying to load a file with an unknown extension, - * Result::Unknown - if an error occurs at a later stage. + * @retval Result::Success When succeeded. + * @retval Result::InvalidArguments In case no data are provided or the @p size is zero or less. + * @retval Result::NonSupport When trying to load a file with an unknown extension. + * @retval Result::Unknown If an error occurs at a later stage. */ Result load(const char* data, uint32_t size) noexcept; @@ -865,19 +901,24 @@ public: * @param[in] w The width of the image in pixels. * @param[in] h The height of the image in pixels. * @param[in] copy Specifies the method of copying the @p data - shallow if @c false and deep id @c true. - * @return Result::Success when succeeded, otherwise the returned value depends on the problem type: - * Result::InvalidArguments - in case no data is provided or the width or the height of the picture is zero or less, - * Result::NonSupport - when trying to load a file with an unknown extension. + * @retval Result::Success When succeeded. + * @retval Result::InvalidArguments In case no data is provided or the width or the height of the picture is zero or less. + * @retval Result::NonSupport When trying to load a file with an unknown extension. */ Result load(uint32_t* data, uint32_t w, uint32_t h, bool copy) noexcept; /** - * @brief ... - * @param[out] x - * @param[out] y - * @param[out] w - * @param[out] h - * @return Result::Success when succeeded, ... otherwise. + * @brief Gets the position and the size of the loaded picture. + * + * For the svg file the returned values are specified in the viewBox attribute. + * For the png and raw files, @p x and @p y are zeros and @p w and @p h indicate the width + * and the height of the picture, respectively. + * + * @param[out] x The horizontal coordinate of the upper left corner of the picture. + * @param[out] y The vertical coordinate of the upper left corner of the picture. + * @param[out] w The picture width. + * @param[out] h The picture height. + * @return Result::Success when succeeded, Result::InsufficientCondition otherwise. */ //TODO: Replace with size(). Remove API Result viewbox(float* x, float* y, float* w, float* h) const noexcept; @@ -951,7 +992,7 @@ public: Result push(std::unique_ptr paint) noexcept; /** - * @brief Sets the size of the memory block, where all the paints pushed into the scene are stored. + * @brief Sets the size of the container, where all the paints pushed into the scene are stored. * * If the number of objects pushed into the scene is known in advance, calling the function * prevents multiple memory reallocation, thus improving the performance. @@ -985,7 +1026,7 @@ public: * * @ingroup ThorVG * - @brief description... + * @brief A class for the rasterisation of graphic elements with a software engine. * */ class TVG_EXPORT SwCanvas final : public Canvas @@ -998,24 +1039,30 @@ public: */ enum Colorspace { - ABGR8888 = 0, ///< - ARGB8888 ///< + ABGR8888 = 0, ///< The channels are joined in the order: alpha, blue, green, red. + ARGB8888 ///< The channels are joined in the order: alpha, red, green, blue. }; /** - * @brief ... - * @param[in] - * @param[in] - * @param[in] - * @param[in] - * @param[in] - * @return Result::Success when succeeded, ... otherwise. + * @brief Sets the target of the rasterisation. + * + * The buffer of a desirable size should be already allocated. + * + * @param[in] buffer A pointer to a memory block of the size @p w x @p h, where the raster data are stored. + * @param[in] stride The stride of the raster image - greater than or equal to @p w. + * @param[in] w The width of the raster image. + * @param[in] h The height of the raster image. + * @param[in] cs The value specifying the way the 32-bits colors should be read/written. + * @retval Result::Success when succeeded. + * @retval Result::MemoryCorruption When casting in the internal function implementation failed. + * @retval Result::InvalidArguments In case no valid pointer is provided or the width, or the height or the stride is zero. + * @retval Result::NonSupport In case the software engine is not enabled in the 'meson_options.txt' file. */ Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h, Colorspace cs) noexcept; /** - * @brief ... - * @return Result::Success when succeeded, ... otherwise. + * @brief Creates a new SwCanvas object. + * @return A unique pointer to the new SwCanvas object when succeeded, @c nullptr if the software engine is not enabled in the 'meson_options.txt' file. */ static std::unique_ptr gen() noexcept; @@ -1028,7 +1075,7 @@ public: * * @ingroup ThorVG * - * @brief description... + * @brief A class for the rasterisation of graphic elements with the OpenGL engine. * */ class TVG_EXPORT GlCanvas final : public Canvas @@ -1037,19 +1084,14 @@ public: ~GlCanvas(); /** - * @brief ... - * @param[in] - * @param[in] - * @param[in] - * @param[in] - * @return Result::Success when succeeded, ... otherwise. + * @brief Sets the target of the rasterisation. */ //TODO: Gl Specific methods. Need gl backend configuration methods as well. Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h) noexcept; /** - * @brief ... - * @return + * @brief Creates a new GlCanvas object. + * @return A unique pointer to the new GlCanvas object when succeeded, @c nullptr if the OpenGL engine is not enabled in the 'meson_options.txt' file. */ static std::unique_ptr gen() noexcept; @@ -1058,33 +1100,36 @@ public: /** - * @class Engine + * @class Initializer * * @ingroup ThorVG * - * @brief description... + * @brief A class that enables initialization and termination of the ThorVG engine. * */ class TVG_EXPORT Initializer final { public: /** - * @brief ... - * - * @param[in] arg ... - * - * @note ... - * - * @return ... - * - * @see ... + * @brief Initializes the ThorVG engine. + * @param[in] engine The engine type - the same as specified in the 'meson_options.txt' file. + * @param[in] threads The number of threads - zero is treated as one. + * @retval Result::Success When succeeded. + * @retval Result::InsufficientCondition An internal error possibly with memory allocation. + * @retval Result::InvalidArguments If unknown engine type chosen. + * @retval Result::NonSupport In case the engine type in the 'meson_options.txt' differs from the one specified in the @p engine argument. + * @retval Result::Unknown Other. */ static Result init(CanvasEngine engine, uint32_t threads) noexcept; /** - * @brief ... - * @param[in] arg ... - * @return ... + * @brief Terminates the ThorVG engine. + * @param[in] engine The engine type - the same as specified in the 'meson_options.txt' file. + * @retval Result::Success When succeeded. + * @retval Result::InsufficientCondition In case there is nothing to be terminated. + * @retval Result::InvalidArguments If unknown engine type chosen. + * @retval Result::NonSupport In case the engine type in the 'meson_options.txt' differs from the one specified in the @p engine argument. + * @retval Result::Unknown Other. */ static Result term(CanvasEngine engine) noexcept; -- 2.7.4 From dda66c71fb744eb4c6d05c5a558b6cc325933ae4 Mon Sep 17 00:00:00 2001 From: JunsuChoi Date: Mon, 26 Apr 2021 16:20:35 +0900 Subject: [PATCH 05/16] infra Actions: If no coding style error, no comment and change action name --- .github/workflows/actions.yml | 2 +- .github/workflows/actions_cpplint.yml | 4 ++-- .github/workflows/cpp_lint_check.sh | 9 ++------- 3 files changed, 5 insertions(+), 10 deletions(-) diff --git a/.github/workflows/actions.yml b/.github/workflows/actions.yml index 14d3730..d680a16 100644 --- a/.github/workflows/actions.yml +++ b/.github/workflows/actions.yml @@ -1,4 +1,4 @@ -name: Continuous-integration +name: Build Test on: pull_request: diff --git a/.github/workflows/actions_cpplint.yml b/.github/workflows/actions_cpplint.yml index da70616..fe42935 100644 --- a/.github/workflows/actions_cpplint.yml +++ b/.github/workflows/actions_cpplint.yml @@ -1,4 +1,4 @@ -name: PullRequest_Checker +name: Check Commit on: pull_request: @@ -6,7 +6,7 @@ on: - master jobs: - build: + coding-style: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 diff --git a/.github/workflows/cpp_lint_check.sh b/.github/workflows/cpp_lint_check.sh index c130da3..405f9e0 100644 --- a/.github/workflows/cpp_lint_check.sh +++ b/.github/workflows/cpp_lint_check.sh @@ -37,7 +37,7 @@ cpplint --filter=-,\ PAYLOAD_CPPLINT=`cat cpp-report.txt` COMMENTS_URL=$(cat $GITHUB_EVENT_PATH | jq -r .pull_request.comments_url) - + echo $COMMENTS_URL echo "Cppcheck errors:" echo $PAYLOAD_CPPLINT @@ -47,13 +47,8 @@ if [[ $PAYLOAD_CPPLINT == *"Total errors found: "* ]]; then OUTPUT+=$'\n```\n' OUTPUT+="$PAYLOAD_CPPLINT" OUTPUT+=$'\n```\n' - -else - OUTPUT+=$'\n**CODING STYLE CHECK**:\n' - OUTPUT+=$'\n```\n' - OUTPUT+="Perfect." - OUTPUT+=$'\n```\n' fi + PAYLOAD=$(echo '{}' | jq --arg body "$OUTPUT" '.body = $body') curl -s -S -H "Authorization: token $GITHUB_TOKEN" --header "Content-Type: application/vnd.github.VERSION.text+json" --data "$PAYLOAD" "$COMMENTS_URL" -- 2.7.4 From 4c723dd4a22224fd9625502167e7cbdef6a74268 Mon Sep 17 00:00:00 2001 From: Mira Grudzinska Date: Sun, 25 Apr 2021 23:40:03 +0200 Subject: [PATCH 06/16] common paint: changed result in composite API A possible error is due to erroneous arguments, so InvalidArgument is return instead of InsufficientCondition --- src/lib/tvgPaint.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib/tvgPaint.cpp b/src/lib/tvgPaint.cpp index 9b0aba7..b40b529 100644 --- a/src/lib/tvgPaint.cpp +++ b/src/lib/tvgPaint.cpp @@ -298,7 +298,7 @@ Paint* Paint::duplicate() const noexcept Result Paint::composite(std::unique_ptr target, CompositeMethod method) const noexcept { if (pImpl->composite(target.release(), method)) return Result::Success; - return Result::InsufficientCondition; + return Result::InvalidArguments; } @@ -316,4 +316,4 @@ Result Paint::opacity(uint8_t o) noexcept uint8_t Paint::opacity() const noexcept { return pImpl->opacity; -} \ No newline at end of file +} -- 2.7.4 From 70e5b36ca8ec2453a3631f49c8a199527fa8b64f Mon Sep 17 00:00:00 2001 From: Mira Grudzinska Date: Wed, 28 Apr 2021 15:03:37 +0200 Subject: [PATCH 07/16] doc common: change of the return value in the composite API --- inc/thorvg.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inc/thorvg.h b/inc/thorvg.h index 98761b3..030eac9 100644 --- a/inc/thorvg.h +++ b/inc/thorvg.h @@ -227,7 +227,7 @@ public: * @brief Sets the composition target object and the composition method. * @param[in] target The pointer to the target object. * @param[in] method The method used to composite the source object with the target. - * @return Result::Success when succeeded, Result::InsufficientCondition otherwise. + * @return Result::Success when succeeded, Result::InvalidArguments otherwise. */ Result composite(std::unique_ptr target, CompositeMethod method) const noexcept; -- 2.7.4 From 71e49d4d73c259c846c83a68269417bf0c37b8c3 Mon Sep 17 00:00:00 2001 From: Michal Szczecinski Date: Fri, 16 Apr 2021 08:37:40 +0200 Subject: [PATCH 08/16] capi: Added Inverted Alpha Mask composition enumeration. Added missing composite method. Backend supports this compostion type. Change-Id: I941e9da3ef325e639c2168b8d0ddc59aba8c2d7a --- inc/thorvg_capi.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/inc/thorvg_capi.h b/inc/thorvg_capi.h index 87c9476..6aae0f8 100644 --- a/inc/thorvg_capi.h +++ b/inc/thorvg_capi.h @@ -108,7 +108,8 @@ typedef enum { typedef enum { TVG_COMPOSITE_METHOD_NONE = 0, TVG_COMPOSITE_METHOD_CLIP_PATH, - TVG_COMPOSITE_METHOD_ALPHA_MASK + TVG_COMPOSITE_METHOD_ALPHA_MASK, + TVG_COMPOSITE_METHOD_INVERSE_ALPHA_MASK, } Tvg_Composite_Method; typedef struct -- 2.7.4 From 45f1fbe6b75cfc0310e421706f9600818c9c7145 Mon Sep 17 00:00:00 2001 From: JunsuChoi Date: Thu, 29 Apr 2021 11:36:12 +0900 Subject: [PATCH 09/16] doc common: Add grouping of C++ api and C api group ThorVG C++ APIs group ThorVGCapi C APIs --- inc/thorvg.h | 29 +++++++---------------------- inc/thorvg_capi.h | 7 +++++++ 2 files changed, 14 insertions(+), 22 deletions(-) diff --git a/inc/thorvg.h b/inc/thorvg.h index 030eac9..91798eb 100644 --- a/inc/thorvg.h +++ b/inc/thorvg.h @@ -49,6 +49,11 @@ class Scene; class Picture; class Canvas; +/** + * @defgroup ThorVG C++ APIs + */ + +/**@{*/ /** * @brief Enumeration specifying the result from the APIs. @@ -161,8 +166,6 @@ struct Matrix /** * @class Paint * - * @ingroup ThorVG - * * @brief A class for managing graphic elements. * * It enables duplication, transformation and composition. @@ -264,8 +267,6 @@ public: /** * @class Fill * - * @ingroup ThorVG - * * @brief A class representing the gradient fill of the Shape object. * * It contains the information about the gradient colors and their arrangement @@ -333,8 +334,6 @@ public: /** * @class Canvas * - * @ingroup ThorVG - * * @brief A class for drawing graphic elements. * * It stores all Paint objects (Shape, Scene, Picture) and creates the buffer, which can be drawn on the screen. @@ -412,8 +411,6 @@ public: /** * @class LinearGradient * - * @ingroup ThorVG - * * @brief A class representing the linear gradient fill of the Shape object. * * Besides the APIs inherited from the Fill class, it enables setting and getting the linear gradient bounds. @@ -467,8 +464,6 @@ public: /** * @class RadialGradient * - * @ingroup ThorVG - * * @brief A class representing the radial gradient fill of the Shape object. * */ @@ -516,8 +511,6 @@ public: /** * @class Shape * - * @ingroup ThorVG - * * @brief A class 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. @@ -853,8 +846,6 @@ public: /** * @class Picture * - * @ingroup ThorVG - * * @brief A 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. @@ -968,8 +959,6 @@ public: /** * @class Scene * - * @ingroup ThorVG - * * @brief A class enabling to hold many Paint objects. * * As a whole they can be transformed, their transparency can be changed, or the composition @@ -1024,8 +1013,6 @@ public: /** * @class SwCanvas * - * @ingroup ThorVG - * * @brief A class for the rasterisation of graphic elements with a software engine. * */ @@ -1073,8 +1060,6 @@ public: /** * @class GlCanvas * - * @ingroup ThorVG - * * @brief A class for the rasterisation of graphic elements with the OpenGL engine. * */ @@ -1102,8 +1087,6 @@ public: /** * @class Initializer * - * @ingroup ThorVG - * * @brief A class that enables initialization and termination of the ThorVG engine. * */ @@ -1136,6 +1119,8 @@ public: _TVG_DISABLE_CTOR(Initializer); }; +/** @}*/ + } //namespace #ifdef __cplusplus diff --git a/inc/thorvg_capi.h b/inc/thorvg_capi.h index 6aae0f8..fce9c43 100644 --- a/inc/thorvg_capi.h +++ b/inc/thorvg_capi.h @@ -38,6 +38,12 @@ typedef struct _Tvg_Canvas Tvg_Canvas; typedef struct _Tvg_Paint Tvg_Paint; typedef struct _Tvg_Gradient Tvg_Gradient; +/** + * \defgroup ThorVGCapi C APIs + */ + +/**@{*/ + /*! * \def TVG_ENGINE_SW * Software raster engine type. @@ -1299,6 +1305,7 @@ TVG_EXPORT Tvg_Result tvg_scene_push(Tvg_Paint* scene, Tvg_Paint* paint); */ TVG_EXPORT Tvg_Result tvg_scene_clear(Tvg_Paint* scene); +/** \}*/ #ifdef __cplusplus } -- 2.7.4 From b722cea56be5847cbe7572298708bfe9a25156e5 Mon Sep 17 00:00:00 2001 From: Mira Grudzinska Date: Wed, 28 Apr 2021 14:10:25 +0200 Subject: [PATCH 10/16] sw_engine: fixing overlapping masks The buffer to which the mask is rastered is only partially cleared. If the object to which the mask is applied overlaps an area where another mask was used, an erroneous image is generated. The buffer clearing area has been increased to the size of the object to which the mask is applied. --- src/lib/tvgPaint.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib/tvgPaint.cpp b/src/lib/tvgPaint.cpp index b40b529..987ddae 100644 --- a/src/lib/tvgPaint.cpp +++ b/src/lib/tvgPaint.cpp @@ -167,7 +167,7 @@ bool Paint::Impl::render(RenderMethod& renderer) /* Note: only ClipPath is processed in update() step. Create a composition image. */ if (cmpTarget && cmpMethod != CompositeMethod::ClipPath) { - auto region = cmpTarget->pImpl->bounds(renderer); + auto region = smethod->bounds(renderer); if (region.w == 0 || region.h == 0) return false; cmp = renderer.target(region); renderer.beginComposite(cmp, CompositeMethod::None, 255); -- 2.7.4 From 9ceba0982f6ee1bf60794e9f5ab42b0f1b507df8 Mon Sep 17 00:00:00 2001 From: JunsuChoi Date: Thu, 29 Apr 2021 14:21:07 +0900 Subject: [PATCH 11/16] 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 From bfe91dabcb401f59682377be688834a281a4ae9d Mon Sep 17 00:00:00 2001 From: JunsuChoi Date: Thu, 29 Apr 2021 15:05:30 +0900 Subject: [PATCH 12/16] doc common: Add enum and struct docs in capi --- inc/thorvg_capi.h | 152 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 93 insertions(+), 59 deletions(-) diff --git a/inc/thorvg_capi.h b/inc/thorvg_capi.h index 155e84e..9555c3f 100644 --- a/inc/thorvg_capi.h +++ b/inc/thorvg_capi.h @@ -83,66 +83,32 @@ typedef struct _Tvg_Gradient Tvg_Gradient; #define TVG_COLORSPACE_ARGB8888 1 +/** + * @brief Enumeration specifying the result from the APIs. + */ typedef enum { - TVG_RESULT_SUCCESS = 0, - TVG_RESULT_INVALID_ARGUMENT, - TVG_RESULT_INSUFFICIENT_CONDITION, - TVG_RESULT_FAILED_ALLOCATION, - TVG_RESULT_MEMORY_CORRUPTION, - TVG_RESULT_NOT_SUPPORTED, - TVG_RESULT_UNKNOWN + TVG_RESULT_SUCCESS = 0, ///< The value returned in case of the correct request execution. + TVG_RESULT_INVALID_ARGUMENT, ///< The value returned in the event of a problem with the arguments given to the API - e.g. empty paths or null pointers. + TVG_RESULT_INSUFFICIENT_CONDITION, ///< The value returned in case the request cannot be processed - e.g. asking for properties of an object, which does not exist. + TVG_RESULT_FAILED_ALLOCATION, ///< The value returned in case of unsuccessful memory allocation. + TVG_RESULT_MEMORY_CORRUPTION, ///< The value returned in the event of bad memory handling - e.g. failing in pointer releasing or casting + TVG_RESULT_NOT_SUPPORTED, ///< The value returned in case of choosing unsupported options. + TVG_RESULT_UNKNOWN ///< The value returned in all other cases. } Tvg_Result; -typedef enum { - TVG_PATH_COMMAND_CLOSE = 0, - TVG_PATH_COMMAND_MOVE_TO, - TVG_PATH_COMMAND_LINE_TO, - TVG_PATH_COMMAND_CUBIC_TO -} Tvg_Path_Command; - - -typedef enum { - TVG_STROKE_CAP_SQUARE = 0, - TVG_STROKE_CAP_ROUND, - TVG_STROKE_CAP_BUTT -} Tvg_Stroke_Cap; - - -typedef enum { - TVG_STROKE_JOIN_BEVEL = 0, - TVG_STROKE_JOIN_ROUND, - TVG_STROKE_JOIN_MITER -} Tvg_Stroke_Join; - - -typedef enum { - TVG_STROKE_FILL_PAD = 0, - TVG_STROKE_FILL_REFLECT, - TVG_STROKE_FILL_REPEAT -} Tvg_Stroke_Fill; - - -typedef enum { - TVG_FILL_RULE_WINDING = 0, - TVG_FILL_RULE_EVEN_ODD -} Tvg_Fill_Rule; - - -typedef enum { - TVG_COMPOSITE_METHOD_NONE = 0, - TVG_COMPOSITE_METHOD_CLIP_PATH, - TVG_COMPOSITE_METHOD_ALPHA_MASK, - TVG_COMPOSITE_METHOD_INVERSE_ALPHA_MASK, -} Tvg_Composite_Method; - - +/** + * @brief A data structure representing a point in two-dimensional space. + */ typedef struct { float x, y; } Tvg_Point; +/** + * @brief A data structure representing a three-dimensional matrix. + */ typedef struct { float e11, e12, e13; @@ -150,14 +116,6 @@ typedef struct float e31, e32, e33; } Tvg_Matrix; - -typedef struct -{ - float offset; - uint8_t r, g, b, a; -} Tvg_Color_Stop; - - /************************************************************************/ /* Engine API */ /************************************************************************/ @@ -504,6 +462,16 @@ TVG_EXPORT Tvg_Result tvg_canvas_sync(Tvg_Canvas* canvas); /************************************************************************/ /* Paint API */ /************************************************************************/ +/** + * @brief Enumeration indicating the method used in the composition of two objects - the target and the source. + */ +typedef enum { + TVG_COMPOSITE_METHOD_NONE = 0, ///< No composition is applied. + TVG_COMPOSITE_METHOD_CLIP_PATH, ///< The intersection of the source and the target is determined and only the resulting pixels from the source are rendered. + TVG_COMPOSITE_METHOD_ALPHA_MASK, ///< The pixels of the source and the target are alpha blended. As a result, only the part of the source, which intersects with the target is visible. + TVG_COMPOSITE_METHOD_INVERSE_ALPHA_MASK, ///< The pixels of the source and the complement to the target's pixels are alpha blended. As a result, only the part of the source which is not covered by the target is visible. +} Tvg_Composite_Method; + /*! * \fn TVG_EXPORT Tvg_Result tvg_paint_del(Tvg_Paint* paint) * \brief The function releases given paint object. The tvg_canvas_clear(canvas, true) or tvg_canvas_del(canvas) @@ -657,10 +625,62 @@ TVG_EXPORT Tvg_Result tvg_paint_set_composite_method(Tvg_Paint* paint, Tvg_Paint * \{ */ - /************************************************************************/ /* Shape API */ /************************************************************************/ + +/** + * @brief Enumeration specifying the values of the path commands accepted by ThorVG. + * + * Not to be confused with the path commands from the svg path element (like M, L, Q, H and many others). + * ThorVG interprets all of them and translates to the ones from the PathCommand values. + */ +typedef enum { + TVG_PATH_COMMAND_CLOSE = 0, ///< Ends the current sub-path and connects it with its initial point - corresponds to Z command in the svg path commands. + TVG_PATH_COMMAND_MOVE_TO, ///< Sets a new initial point of the sub-path and a new current point - corresponds to M command in the svg path commands. + TVG_PATH_COMMAND_LINE_TO, ///< Draws a line from the current point to the given point and sets a new value of the current point - corresponds to L command in the svg path commands. + TVG_PATH_COMMAND_CUBIC_TO ///< Draws a cubic Bezier curve from the current point to the given point using two given control points and sets a new value of the current point - corresponds to C command in the svg path commands. +} Tvg_Path_Command; + + +/** + * @brief Enumeration determining the ending type of a stroke in the open sub-paths. + */ +typedef enum { + TVG_STROKE_CAP_SQUARE = 0, ///< The stroke is extended in both endpoints of a sub-path by a rectangle, with the width equal to the stroke width and the length equal to the half of the stroke width. For zero length sub-paths the square is rendered with the size of the stroke width. + TVG_STROKE_CAP_ROUND, ///< The stroke is extended in both endpoints of a sub-path by a half circle, with a radius equal to the half of a stroke width. For zero length sub-paths a full circle is rendered. + TVG_STROKE_CAP_BUTT ///< The stroke ends exactly at each of the two endpoints of a sub-path. For zero length sub-paths no stroke is rendered. +} Tvg_Stroke_Cap; + + +/** + * @brief Enumeration specifying how to fill the area outside the gradient bounds. + */ +typedef enum { + TVG_STROKE_JOIN_BEVEL = 0, ///< The outer corner of the joined path segments is bevelled at the join point. The triangular region of the corner is enclosed by a straight line between the outer corners of each stroke. + TVG_STROKE_JOIN_ROUND, ///< The outer corner of the joined path segments is rounded. The circular region is centered at the join point. + TVG_STROKE_JOIN_MITER ///< The outer corner of the joined path segments is spiked. The spike is created by extension beyond the join point of the outer edges of the stroke until they intersect. In case the extension goes beyond the limit, the join style is converted to the Bevel style. +} Tvg_Stroke_Join; + + +/** + * @brief Enumeration specifying how to fill the area outside the gradient bounds. + */ +typedef enum { + TVG_STROKE_FILL_PAD = 0, ///< The remaining area is filled with the closest stop color. + TVG_STROKE_FILL_REFLECT, ///< The gradient pattern is reflected outside the gradient area until the expected region is filled. + TVG_STROKE_FILL_REPEAT ///< The gradient pattern is repeated continuously beyond the gradient area until the expected region is filled. +} Tvg_Stroke_Fill; + + +/** + * @brief Enumeration specifying the algorithm used to establish which parts of the shape are treated as the inside of the shape. + */ +typedef enum { + TVG_FILL_RULE_WINDING = 0, ///< A line from the point to a location outside the shape is drawn. The intersections of the line with the path segment of the shape are counted. Starting from zero, if the path segment of the shape crosses the line clockwise, one is added, otherwise one is subtracted. If the resulting sum is non zero, the point is inside the shape. + TVG_FILL_RULE_EVEN_ODD ///< A line from the point to a location outside the shape is drawn and its intersections with the path segments of the shape are counted. If the number of intersections is an odd number, the point is inside the shape. +} Tvg_Fill_Rule; + /*! * \fn TVG_EXPORT Tvg_Paint* tvg_shape_new() * \brief The function creates a new shape @@ -1144,6 +1164,20 @@ TVG_EXPORT Tvg_Result tvg_shape_get_gradient(const Tvg_Paint* paint, Tvg_Gradien * \{ */ +/*! +* \struct Tvg_Color_Stop +* \brief A data structure storing the information about the color and its relative position inside the gradient bounds. +*/ +typedef struct +{ + float offset; /**< The relative position of the color. */ + uint8_t r; /**< The red color channel value in the range [0 ~ 255]. */ + uint8_t g; /**< The green color channel value in the range [0 ~ 255]. */ + uint8_t b; /**< The blue color channel value in the range [0 ~ 255]. */ + uint8_t a; /**< The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. */ +} Tvg_Color_Stop; + + /************************************************************************/ /* Gradient API */ /************************************************************************/ -- 2.7.4 From a3fefcaa2549062faf358e06531f92ffbdfca18c Mon Sep 17 00:00:00 2001 From: Hermet Park Date: Fri, 30 Apr 2021 18:53:20 +0900 Subject: [PATCH 13/16] doc: polish up api documentation. --- inc/thorvg.h | 640 +++++++++++++++++++++++++++++++----------------------- inc/thorvg_capi.h | 6 +- 2 files changed, 375 insertions(+), 271 deletions(-) diff --git a/inc/thorvg.h b/inc/thorvg.h index 91798eb..d391f6e 100644 --- a/inc/thorvg.h +++ b/inc/thorvg.h @@ -50,7 +50,7 @@ class Picture; class Canvas; /** - * @defgroup ThorVG C++ APIs + * @defgroup ThorVG */ /**@{*/ @@ -70,17 +70,17 @@ enum class TVG_EXPORT Result }; /** - * @brief Enumeration specifying the values of the path commands accepted by ThorVG. + * @brief Enumeration specifying the values of the path commands accepted by TVG. * * Not to be confused with the path commands from the svg path element (like M, L, Q, H and many others). - * ThorVG interprets all of them and translates to the ones from the PathCommand values. + * TVG interprets all of them and translates to the ones from the PathCommand values. */ enum class TVG_EXPORT PathCommand { - Close = 0, ///< Ends the current sub-path and connects it with its initial point - corresponds to Z command in the svg path commands. - MoveTo, ///< Sets a new initial point of the sub-path and a new current point - corresponds to M command in the svg path commands. - LineTo, ///< Draws a line from the current point to the given point and sets a new value of the current point - corresponds to L command in the svg path commands. - CubicTo ///< Draws a cubic Bezier curve from the current point to the given point using two given control points and sets a new value of the current point - corresponds to C command in the svg path commands. + Close = 0, ///< Ends the current sub-path and connects it with its initial point. This command expects 1 point: close position. + MoveTo, ///< Sets a new initial point of the sub-path and a new current point. This command expects 1 point: moving position. + LineTo, ///< Draws a line from the current point to the given point and sets a new value of the current point. This command expects 1 point: end position of the line. + CubicTo ///< Draws a cubic Bezier curve from the current point to the given point using two given control points and sets a new value of the current point. This command expects 3 points: control 1, control 2, end. }; /** @@ -88,9 +88,9 @@ enum class TVG_EXPORT PathCommand */ enum class TVG_EXPORT StrokeCap { - Square = 0, ///< The stroke is extended in both endpoints of a sub-path by a rectangle, with the width equal to the stroke width and the length equal to the half of the stroke width. For zero length sub-paths the square is rendered with the size of the stroke width. - Round, ///< The stroke is extended in both endpoints of a sub-path by a half circle, with a radius equal to the half of a stroke width. For zero length sub-paths a full circle is rendered. - Butt ///< The stroke ends exactly at each of the two endpoints of a sub-path. For zero length sub-paths no stroke is rendered. + Square = 0, ///< The stroke is extended in both end-points of a sub-path by a rectangle, with the width equal to the stroke width and the length equal to the half of the stroke width. For zero length sub-paths the square is rendered with the size of the stroke width. + Round, ///< The stroke is extended in both end-points of a sub-path by a half circle, with a radius equal to the half of a stroke width. For zero length sub-paths a full circle is rendered. + Butt ///< The stroke ends exactly at each of the two end-points of a sub-path. For zero length sub-paths no stroke is rendered. }; /** @@ -134,12 +134,12 @@ enum class TVG_EXPORT CompositeMethod }; /** - * @brief Enumeration specifying the engine type used for the graphic rendering. + * @brief Enumeration specifying the engine type used for the graphics backend. For multiple backeneds, Bitwise operation is allowed. */ enum class TVG_EXPORT CanvasEngine { - Sw = (1 << 1), ///< CPU rendering. - Gl = (1 << 2) ///< OpenGL rendering. + Sw = (1 << 1), ///< CPU rasterizer. + Gl = (1 << 2) ///< OpenGL rasterizer. }; @@ -154,6 +154,10 @@ struct Point /** * @brief A data structure representing a three-dimensional matrix. + * + * The elements e11, e12, e21 and e22 represent the rotation matrix, including the scaling factor. + * The elements e13 and e23 determine the translation of the object along the x and y-axis, respectively. + * The elements e31 and e32 are set to 0, e33 is set to 1. */ struct Matrix { @@ -166,9 +170,11 @@ struct Matrix /** * @class Paint * - * @brief A class for managing graphic elements. + * @brief A abstract class for managing graphical elements. * - * It enables duplication, transformation and composition. + * Basically a graphical elements in TVG is composed as an object in a scene (Canvas). + * Paint represents a graphical object, suggest common behaviors such as duplication, transformation and composition, etc. + * TVG recommends user to regard a paint as a pack of volatile commands, they can prepare a paint then request Canvas to run it. * */ class TVG_EXPORT Paint @@ -177,20 +183,23 @@ public: virtual ~Paint(); /** - * @brief Sets the angle by which the object is rotated. + * @brief Sets the angle by which object is rotated. * * The angle in measured clockwise from the horizontal axis. * The rotational axis passes through the point on the object with zero coordinates. * * @param[in] degree The value of the angle in degrees. - * @return Result::Success when succeeded, Result::FailedAllocation otherwise. + * + * @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise. */ Result rotate(float degree) noexcept; /** * @brief Sets the scale value of the object. - * @param[in] factor The value of the scaling factor. - * @return Result::Success when succeeded, Result::FailedAllocation otherwise. + * + * @param[in] factor The value of the scaling factor. Default value is 1. + * + * @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise. */ Result scale(float factor) noexcept; @@ -198,11 +207,12 @@ public: * @brief Sets the values by which the object is moved in a two-dimensional space. * * The origin of the coordinate system is in the upper left corner of the canvas. - * The horizontal and vertical axes point to the right and down, respectively. + * The horizontal and vertical axes points to the right and down, respectively. * * @param[in] x The value of the horizontal shift. * @param[in] y The value of the vertical shift. - * @return Result::Success when succeeded, Result::FailedAllocation otherwise. + * + * @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise. */ Result translate(float x, float y) noexcept; @@ -210,51 +220,62 @@ public: * @brief Sets the matrix of the affine transformation for the object. * * The augmented matrix of the transformation is expected to be given. - * The elements e11, e12, e21 and e22 represent the rotation matrix, including the scaling factor. - * The elements e13 and e23 determine the translation of the object along the x and y-axis, respectively. - * The element e31 and e32 are set to 0, e33 is set to 1. * * @param[in] m The 3x3 augmented matrix. - * @return Result::Success when succeeded, Result::FailedAllocation otherwise. + * + * @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise. + * */ Result transform(const Matrix& m) noexcept; /** * @brief Sets the opacity of the object. + * * @param[in] o The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. - * @return Result::Success. + * + * @return @c Result::Success. + * + * @note A half-translucent paint by opacity may require multiple render pass for composition, TVG recommends to avoid opacity change as possible. */ Result opacity(uint8_t o) noexcept; /** * @brief Sets the composition target object and the composition method. - * @param[in] target The pointer to the target object. + * + * @param[in] target The paint to the target object. * @param[in] method The method used to composite the source object with the target. - * @return Result::Success when succeeded, Result::InvalidArguments otherwise. + * + * @return @c Result::Success when succeed, @c Result::InvalidArguments otherwise. + * */ Result composite(std::unique_ptr target, CompositeMethod method) const noexcept; /** - * @brief Gets the bounding box of the object before any transformation. + * @brief Gets the bounding box of the paint object before any transformation. + * * @param[out] x The x coordinate of the upper left corner of the object. * @param[out] y The y coordinate of the upper left corner of the object. * @param[out] w The width of the object. * @param[out] h The height of the object. - * @return Result::Success when succeeded, Result::InsufficientCondition otherwise. + * + * @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise. + * + * @note bounding box doesn't indicate the rendering region in the result but primitive region of the object. */ Result bounds(float* x, float* y, float* w, float* h) const noexcept; /** * @brief Duplicates the object. * - * Creates a new object and sets all its properties as in the original object. + * Creates a new object and sets all properties as in the original object. * - * @return The pointer to the created object when succeeded, @c nullptr otherwise. + * @return The created object when succeed, @c nullptr otherwise. */ Paint* duplicate() const noexcept; /** * @brief Gets the opacity value of the object. + * * @return The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. */ uint8_t opacity() const noexcept; @@ -267,7 +288,7 @@ public: /** * @class Fill * - * @brief A class representing the gradient fill of the Shape object. + * @brief A abstract class 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 @@ -294,35 +315,45 @@ public: /** * @brief Sets the parameters of the colors of the gradient and their position. - * @param[in] colorStops An array of the ColorStop objects. - * @param[in] cnt The size of the @p colorStops array equal to the colors number used in the gradient. - * @return Result::Success. + * + * @param[in] colorStops An array of ColorStop data structure. + * @param[in] cnt The count of the @p colorStops array equal to the colors number used in the gradient. + * + * @return @c Result::Success when succeed. */ Result colorStops(const ColorStop* colorStops, uint32_t cnt) noexcept; /** * @brief Sets the FillSpread value, which specifies how to fill the area outside the gradient bounds. + * * @param[in] s The FillSpread value. - * @return Result::Success. + * + * @return @c Result::Success when succeed. */ Result spread(FillSpread s) noexcept; /** - * @brief Gets the parameters of the colors of the gradient, their position and their number. - * @param[in] colorStops A pointer to the memory location, where the array of the gradient's ColorStop objects is stored. + * @brief Gets the parameters of the colors of the gradient, their position and number. + * + * @param[in] colorStops A pointer to the memory location, where the array of the gradient's ColorStop is stored. + * * @return The number of colors used in the gradient. This value corresponds to the length of the @p colorStops array. */ uint32_t colorStops(const ColorStop** colorStops) const noexcept; /** * @brief Gets the FillSpread value of the fill. - * @return The set FillSpread enumeration values. + * + * @return The FillSpread value of this Fill. */ FillSpread spread() const noexcept; /** * @brief Creates a copy of the Fill object. - * @return A pointer to a newly created Fill object with the properties copied from the original. Fill object when succeeded, @c nullptr otherwise. + * + * Return a newly created Fill object with the properties copied from the original. + * + * @return A copied Fill object when succeed, @c nullptr otherwise. */ Fill* duplicate() const noexcept; @@ -334,9 +365,12 @@ public: /** * @class Canvas * - * @brief A class for drawing graphic elements. + * @brief A abstract class for drawing graphical elements. + * + * A canvas is a unit to a drawing target. It sets up drawing engine and buffer, which can be drawn on the screen, it also manages given Paint objects. * - * It stores all Paint objects (Shape, Scene, Picture) and creates the buffer, which can be drawn on the screen. + * @note Canvas behavior depends on the raster engine though its drawing result is expected to be identical. + * @warning Paints are belongs to a Canvas, they can't be shared among multiple Canvases. */ class TVG_EXPORT Canvas { @@ -351,56 +385,74 @@ public: * prevents multiple memory reallocation, thus improving the performance. * * @param[in] n The number of objects for which the memory is to be reserved. + * * @return Result::Success. */ Result reserve(uint32_t n) noexcept; /** - * @brief Passes the Paint object to the Canvas. + * @brief Passes drawing elements to the Canvas using Paint objects. + * + * 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 count of push() in the advance, please call reserve(). * - * The function may be called many times and all passed objects will be rendered. - * Calling it initializes the data preparation of the chosen engine type. + * @param[in] paint A Paint object to be drawn. * - * @param[in] paint A unique pointer to the Paint object. - * @retval Result::Success When succeeded. - * @retval Result::MemoryCorruption In case a @c nullptr is passed as the argument. - * @retval Result::InsufficientCondition An internal error. + * @retval @c Result::Success when succeed. + * @retval @c Result::MemoryCorruption In case a @c nullptr is passed as the argument. + * @retval @c Result::InsufficientCondition An internal error. + * + * @note Rendering order of the paints are in the order of the push. Thus if you mind a layering, sorting the paints before pushing them. + * @see Canvas::reserve() + * @see Canvas::clear() */ virtual Result push(std::unique_ptr paint) noexcept; /** - * @brief Sets the total number of the paints pushed into the scene to be zero. - * Depending on the value of the given argument, the memory is free or not. + * @brief Sets the total number of the paints pushed into the canvas to be zero. + * Depending on the value of the given argument @p free, the Paints were free or not. * * @param[in] free If @c then true the memory occupied by paints is deallocated, otherwise it is not. - * return Result::Success when succeeded, Result::InsufficientCondition otherwise. + * + * @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise. + * + * @warning If you don't free the paints, they are totally dangled, they are supposed to be reused otherwise you are responsible for their lives. Thus please use that @p free option when you know how it works, otherwise it's not recommended. */ virtual Result clear(bool free = true) noexcept; /** - * @brief Updates the chosen Paint object or all objects from the Canvas object. + * @brief Request the canvas to update the paint objects. * - * If a @c nullptr is passed all objects from the Canvas are updated. - * Otherwise only the paint to which the given argument points. + * If a @c nullptr is passed all paint objects retained by the Canvas are updated, otherwise only the paint to which the given @p paint. * * @param[in] paint A pointer to the Paint object or @c nullptr. - * return Result::Success when succeeded, Result::InsufficientCondition otherwise. + * + * @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise. + * + * @note Updation behavior could be asynchronous by thread option. */ virtual Result update(Paint* paint) noexcept; /** - * @brief Draws all objects from the Canvas object. - * return Result::Success when succeeded, Result::InsufficientCondition otherwise. + * @brief Request the canvas to draw paint objects. + * + * @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise. + * + * @note Drawing could be asynchronous by thread option. To guarantee the done of drawing job, call sync(). + * @see Canvas::sync() */ virtual Result draw() noexcept; /** - * @brief Guaranties that all Paint objects from the Canvas object are already rendered. + * @brief Guarantees that drawing task is finished. + * + * The Canvas rendering can be performed asynchronously. To make sure that rendering is finished, + * the sync() should be called after the draw(). * - * The Canvas components can be rendered asynchronously. To make sure, that all of them - * are ready, the sync API should be called after the draw API. + * @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise. * - * return Result::Success when succeeded, Result::InsufficientCondition otherwise. + * @see Canvas::draw() */ virtual Result sync() noexcept; @@ -432,7 +484,8 @@ public: * @param[in] y1 The vertical coordinate of the first point used to determine the gradient bounds. * @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 succeeded, Result::InvalidArguments otherwise. + * + * @return @c Result::Success when succeed, @c Result::InvalidArguments otherwise. */ Result linear(float x1, float y1, float x2, float y2) noexcept; @@ -447,13 +500,15 @@ public: * @param[out] y1 The vertical coordinate of the first point used to determine the gradient bounds. * @param[out] x2 The horizontal coordinate of the second point used to determine the gradient bounds. * @param[out] y2 The vertical coordinate of the second point used to determine the gradient bounds. - * @return Result::Success. + * + * @return @c Result::Success when succeed. */ Result linear(float* x1, float* y1, float* x2, float* y2) const noexcept; /** * @brief Creates a new LinearGradient object. - * @return A unique pointer to the new LinearGradient object. + * + * @return A new LinearGradient object. */ static std::unique_ptr gen() noexcept; @@ -475,32 +530,33 @@ public: /** * @brief Sets the radial gradient bounds. * - * The radial gradient bounds are defined as a circle centered in a given - * point (cx, cy) of a given radius. + * The radial gradient bounds are defined as a circle centered in a given point (cx, cy) of a given radius. * * @param[in] cx The horizontal coordinate of the center of the bounding circle. * @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 succeeded, Result::InvalidArguments otherwise. + * + * @return @c Result::Success when succeed, @c Result::InvalidArguments otherwise. */ Result radial(float cx, float cy, float radius) noexcept; /** * @brief Gets the radial gradient bounds. * - * The radial gradient bounds are defined as a circle centered in a given - * point (cx, cy) of a given radius. + * The radial gradient bounds are defined as a circle centered in a given point (cx, cy) of a given radius. * * @param[out] cx The horizontal coordinate of the center of the bounding circle. * @param[out] cy The vertical coordinate of the center of the bounding circle. * @param[out] radius The radius of the bounding circle. - * @return Result::Success. + * + * @return @c Result::Success when succeed. */ Result radial(float* cx, float* cy, float* radius) const noexcept; /** * @brief Creates a new RadialGradient object. - * @return A unique pointer to the new RadialGradient object. + * + * @return A new RadialGradient object. */ static std::unique_ptr gen() noexcept; @@ -513,8 +569,12 @@ public: * * @brief A class 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. + * A shape is consisted of major 3 properties: shape outline, stroking, filling. The outline in the Shape is retained as the pathe. + * Path can be composed by accumulating primitive commands such as moveTo(), lineTo(), curbicTo(), or complete shape interfaces such as appendRect(), appendCircle(), etc. + * Path could be consisten of sub-pathes, one sub-path is determined by close commoand. + * + * Stroke of Shape is an optional property in a certain case if the shape needs to be represented with/without outline borders. + * It's efficient since the shape path and the stroking path can be shared with each other. It's also convenient when controlling both in one context. */ class TVG_EXPORT Shape final : public Paint { @@ -522,12 +582,13 @@ public: ~Shape(); /** - * @brief Resets the information about the shape's path. + * @brief Resets the properties of shape path. * - * The information about the color, the fill and the stroke is kept. - * The memory, where the path data is stored, is not deallocated at this stage. + * The properties of the color, fill and the stroke is kept. * - * @return Result::Success. + * @return @c Result::Success when succeed. + * + * @note The memory, where the path data is stored, is not deallocated at this stage for caching effect. */ Result reset() noexcept; @@ -535,36 +596,33 @@ public: * @brief Sets the initial point of the sub-path. * * The value of the current point is set to the given point. - * Corresponds to the M command from the svg path commands. * * @param[in] x The horizontal coordinate of the initial point of the sub-path. * @param[in] y The vertical coordinate of the initial point of the sub-path. - * @return Result::Success. + * + * @return @c Result::Success when succeed. */ Result moveTo(float x, float y) noexcept; /** - * @brief Adds a new point to the sub-path, which results in drawing a line from the current - * point to the given endpoint. + * @brief Adds a new point to the sub-path, which results in drawing a line from the current point to the given end-point. * - * The value of the current point is set to the given endpoint. - * Corresponds to the L command from the svg path commands. - * In case this is the first command in the path, it corresponds to the moveTo command. + * The value of the current point is set to the given end-point. * * @param[in] x The horizontal coordinate of the endpoint of the line. * @param[in] y The vertical coordinate of the endpoint of the line. - * @return Result::Success. + * + * @return @c Result::Success when succeed. + * + * @note In case this is the first command in the path, it corresponds to the moveTo command. */ Result lineTo(float x, float y) noexcept; /** * @brief Adds new points to the sub-path, which results in drawing a cubic Bezier curve starting - * at the current point and ending at the given endpoint (x, y) using the control points (cx1, cy1) - * and (cx2, cy2). + * at the current point and ending at the given end-point (@p x, @p y) using the control points (@p cx1, @p cy1) and (@p cx2, @p cy2). * - * The value of the current point is set to the given endpoint. - * Corresponds to the C command from the svg path commands. - * In case this is the first command in the path, no data from the path are rendered. + * The value of the current point is set to the given end-point. * * @param[in] cx1 The horizontal coordinate of the 1st control point. * @param[in] cy1 The vertical coordinate of the 1st control point. @@ -572,33 +630,32 @@ public: * @param[in] cy2 The vertical coordinate of the 2nd control point. * @param[in] x The horizontal coordinate of the endpoint of the curve. * @param[in] y The vertical coordinate of the endpoint of the curve. - * @return Result::Success. + * + * @return @c Result::Success when succeed. + * + * @note In case this is the first command in the path, no data from the path are rendered. */ Result cubicTo(float cx1, float cy1, float cx2, float cy2, float x, float y) noexcept; /** - * @brief Closes the current sub-path by drawing a line from the current point to the initial point - * of the sub-path. + * @brief Closes the current sub-path by drawing a line from the current point to the initial point of the sub-path. * * The value of the current point is set to the initial point of the closed sub-path. - * Corresponds to the Z command from the svg path commands. - * In case the sub-path does not contain any points, this function has no effect. * - * @return Result::Success. + * @return @c Result::Success when succeed. + * + * @note In case the sub-path does not contain any points, this function has no effect. */ Result close() noexcept; /** * @brief Appends a rectangle to the path. * - * The rectangle with rounded corners can be achieved by setting non-zero values to the @p rx - * and @p ry arguments. The @p rx and @p ry values specify the radii of the ellipse defining - * the rounding of the corners. - * For the @p rx and @p ry values greater than the half of the width and the half of the height, - * respectively, an ellipse is drawn. + * The rectangle with rounded corners can be achieved by setting non-zero values to @p rx and @p ry arguments. + * The @p rx and @p ry values specify the radius of the ellipse defining the rounding of the corners. + * For the @p rx and @p ry values less than the half of the width and the half of the height of respectively, an ellipse is drawn. * - * The position of the rectangle is specified by the coordinates of its upper left - * corner - the @p x and the @p y arguments. + * The position of the rectangle is specified by the coordinates of its upper left corner - @p x and @p y arguments. * * The rectangle is treated as a new sub-path - it is not connected with the previous sub-path. * @@ -611,15 +668,17 @@ public: * @param[in] h The height of the rectangle. * @param[in] rx The x-axis radius of the ellipse defining the rounded corners of the rectangle. * @param[in] ry The y-axis radius of the ellipse defining the rounded corners of the rectangle. - * @return Result::Success. + * + * @return @c Result::Success when succeed. + * + * @note if @p rx and @p ry is greater than half of @p w and half of @p h, the shape becomes to a circle. */ Result appendRect(float x, float y, float w, float h, float rx, float ry) noexcept; /** * @brief Appends an ellipse to the path. * - * The position of the ellipse is specified by the coordinates of its center - the @p cx and - * the @p cy arguments. + * The position of the ellipse is specified by the coordinates of its center - @p cx and @p cy arguments. * * The ellipse is treated as a new sub-path - it is not connected with the previous sub-path. * @@ -629,7 +688,8 @@ public: * @param[in] cy The vertical coordinate of the center of the ellipse. * @param[in] rx The x-axis radius of the ellipse. * @param[in] ry The y-axis radius of the ellipse. - * @return Result::Success. + * + * @return @c Result::Success when succeed. */ Result appendCircle(float cx, float cy, float rx, float ry) noexcept; @@ -637,21 +697,18 @@ public: * @brief Appends a circular arc to the path. * * The arc is treated as a new sub-path - it is not connected with the previous sub-path. - * - * The current point value is set to the endpoint of the arc in case @p pie is @c false, - * and to the center of the arc otherwise. - * - * Setting @p sweep value greater than 360 degrees, is equivalent to calling appendCircle(cx, cy, radius, radius). + * The current point value is set to the end-point of the arc in case @p pie is @c false and to the center of the arc otherwise. * * @param[in] cx The horizontal coordinate of the center of the arc. * @param[in] cy The vertical coordinate of the center of the arc. * @param[in] radius The radius of the arc. - * @param[in] startAngle The start angle of the arc given in degrees, measured - * counterclockwise from the horizontal line. - * @param[in] sweep The central angle of the arc given in degrees, measured - * counterclockwise from the @p startAngle. - * @param[in] pie Specifies whether to draw radii from the arc's center to both of its endpoints - drawn if @c true. - * @return Result::Success. + * @param[in] startAngle The start angle of the arc given in degrees, measured counter clockwise from the horizontal line. + * @param[in] sweep The central angle of the arc given in degrees, measured counter clock-wise from @p startAngle. + * @param[in] pie Specifies whether to draw radius from the arc's center to both of its end-point - drawn if @c true. + * + * @return @c Result::Success when succeed. + * + * @note Setting @p sweep value greater than 360 degrees, is equivalent to calling appendCircle(cx, cy, radius, radius). */ Result appendArc(float cx, float cy, float radius, float startAngle, float sweep, bool pie) noexcept; @@ -659,83 +716,99 @@ public: * @brief Appends a given sub-path to the path. * * The current point value is set to the last point from the sub-path. - * - * For each command from the @p cmds array, an appropriate number of points in @p pts array should be specified, - * as defined for the svg commands. + * For each command from the @p cmds array, an appropriate number of points in @p pts array should be specified. * * @param[in] cmds The array of the commands in the sub-path. * @param[in] cmdCnt The number of the sub-path's commands. * @param[in] pts The array of the two-dimensional points. * @param[in] ptsCnt The number of the points in the @p pts array. - * @return Result::Success when succeeded, Result::InvalidArguments otherwise. + * + * @return @c Result::Success when succeed, @c Result::InvalidArguments otherwise. + * + * @note This interface is designed for optimal path setting if the caller has a completed path commands already. */ Result appendPath(const PathCommand* cmds, uint32_t cmdCnt, const Point* pts, uint32_t ptsCnt) noexcept; /** * @brief Sets the stroke width for all of the figures from the path. - * @param[in] width The width of the stroke. - * @return Result::Success when succeeded, Result::FailedAllocation otherwise. + * + * @param[in] width The width of the stroke. The default value is 0. + * + * @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise. */ Result stroke(float width) noexcept; /** * @brief Sets the color of the stroke for all of the figures from the path. - * @param[in] r The red color channel value in the range [0 ~ 255]. - * @param[in] g The green color channel value in the range [0 ~ 255]. - * @param[in] b The blue color channel value in the range [0 ~ 255]. - * @param[in] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. - * @return Result::Success when succeeded, Result::FailedAllocation otherwise. + * + * @param[in] r The red color channel value in the range [0 ~ 255]. The default value is 0. + * @param[in] g The green color channel value in the range [0 ~ 255]. The default value is 0. + * @param[in] b The blue color channel value in the range [0 ~ 255]. The default value is 0. + * @param[in] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0. + * + * @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise. */ Result stroke(uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept; /** * @brief Sets the gradient fill of the stroke for all of the figures from the path.. - * @param[in] The unique pointer to the gradient fill. - * @retval Result::Success When succeeded. - * @retval Result::FailedAllocation An internal error with a memory allocation for an object to be filled. - * @retval Result::MemoryCorruption In case a @c nullptr is passed as the argument. + * + * @param[in] The gradient fill. + * + * @retval @c Result::Success When succeed. + * @retval @c Result::FailedAllocation An internal error with a memory allocation for an object to be filled. + * @retval @c Result::MemoryCorruption In case a @c nullptr is passed as the argument. */ Result stroke(std::unique_ptr f) noexcept; /** * @brief Sets the dash pattern of the stroke. * - * If any of the dash pattern values is zero, this function has no effect. - * * @param[in] dashPattern The array of consecutive pair values of the dash length and the gap length. - * @param[in] cnt The length of the @p dashPattern array. - * @retval Result::Success When succeeded. - * @retval Result::FailedAllocation An internal error with a memory allocation for an object to be dashed. - * @retval Result::InvalidArguments In case a @c nullptr is passed as the @p dashPattern, + * @param[in] cnt The length of @p dashPattern array. + * + * @retval @c Result::Success when succeed. + * @retval @c Result::FailedAllocation An internal error with a memory allocation for an object to be dashed. + * @retval @c Result::InvalidArguments In case a @c nullptr is passed as the @p dashPattern, * the given length of the array is less than two or any of the @p dashPattern values is zero or less. + * + * @note If any of the dash pattern values is zero, this function has no effect. */ Result stroke(const float* dashPattern, uint32_t cnt) noexcept; /** * @brief Sets the cap style of the stroke in the open sub-paths. - * @param[in] cap The cap style value. - * @return Result::Success when succeeded, Result::FailedAllocation otherwise. + * + * @param[in] cap The cap style value. The default value is @c StrokeCap::Square. + * + * @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise. */ Result stroke(StrokeCap cap) noexcept; /** * @brief Sets the join style for stroked path segments. + * * The join style will be used for joining the two line segment while stroking the path. - * @param[in] join The join style value. - * @return Result::Success when succeeded, Result::FailedAllocation otherwise. + * + * @param[in] join The join style value. The default value is @c StrokeJoin::Bevel. + * + * @return @c Result::Success when succeed, @c Result::FailedAllocation otherwise. */ Result stroke(StrokeJoin join) noexcept; /** - * @brief Sets the color of the fill for all of the figures from the path. + * @brief Sets the solid color for all of the figures from the path. * * The parts of the shape defined as inner are colored. * - * @param[in] r The red color channel value in the range [0 ~ 255]. - * @param[in] g The green color channel value in the range [0 ~ 255]. - * @param[in] b The blue color channel value in the range [0 ~ 255]. - * @param[in] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. - * @return Result::Success. + * @param[in] r The red color channel value in the range [0 ~ 255]. The default value is 0. + * @param[in] g The green color channel value in the range [0 ~ 255]. The default value is 0. + * @param[in] b The blue color channel value in the range [0 ~ 255]. The default value is 0. + * @param[in] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0. + * + * @return @c Result::Success when succeed. + * + * @note Either solid color or gradient fill which is lastly set will be applied. */ Result fill(uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept; @@ -745,97 +818,119 @@ public: * The parts of the shape defined as inner are filled. * * @param[in] f The unique pointer to the gradient fill. - * @return Result::Success when succeeded, Result::MemoryCorruption otherwise. + * + * @return @c Result::Success when succeed, @c Result::MemoryCorruption otherwise. + * + * @note Either solid color or gradient fill which is lastly set will be applied. */ Result fill(std::unique_ptr f) noexcept; /** * @brief Sets the fill rule for the Shape object. + * * @param[in] r The fill rule value. - * @return Result::Success. + * + * @return @c Result::Success when succeed. */ Result fill(FillRule r) noexcept; /** * @brief Gets the commands data of the path. + * * @param[out] cmds The pointer to the array of the commands from the path. - * @return The length of the @p cmds array when succeeded, zero otherwise. + * + * @return The length of the @p cmds array when succeed, zero otherwise. */ uint32_t pathCommands(const PathCommand** cmds) const noexcept; /** * @brief Gets the points values of the path. + * * @param[out] pts The pointer to the array of the two-dimensional points from the path. - * @return The length of the @p pts array when succeeded, zero otherwise. + * + * @return The length of the @p pts array when succeed, zero otherwise. */ uint32_t pathCoords(const Point** pts) const noexcept; /** * @brief Gets the pointer to the gradient fill of the shape. - * @return The pointer to the gradient fill of the stroke when succeeded, @c nullptr in case no fill was set. + * + * @return The pointer to the gradient fill of the stroke when succeed, @c nullptr in case no fill was set. */ const Fill* fill() const noexcept; /** - * @brief Gets the color of the shape's fill. + * @brief Gets the solid color of the shape. + * * @param[out] r The red color channel value in the range [0 ~ 255]. * @param[out] g The green color channel value in the range [0 ~ 255]. * @param[out] b The blue color channel value in the range [0 ~ 255]. * @param[out] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. - * @return Result::Success. + * + * @return @c Result::Success when succeed. */ Result fillColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a) const noexcept; /** * @brief Gets the fill rule value. + * * @return The fill rule value of the shape. */ FillRule fillRule() const noexcept; /** * @brief Gets the stroke width. - * @return The stroke width value when succeeded, zero if no stroke was set. + * + * @return The stroke width value when succeed, zero if no stroke was set. */ float strokeWidth() const noexcept; /** * @brief Gets the color of the shape's stroke. + * * @param[out] r The red color channel value in the range [0 ~ 255]. * @param[out] g The green color channel value in the range [0 ~ 255]. * @param[out] b The blue color channel value in the range [0 ~ 255]. * @param[out] a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. - * @return Result::Success when succeeded, Result::InsufficientCondition otherwise. + * + * @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise. */ Result strokeColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a) const noexcept; /** * @brief Gets the pointer to the gradient fill of the stroke. - * @return The pointer to the gradient fill of the stroke when succeeded, @c nullptr otherwise. + * + * @return The pointer to the gradient fill of the stroke when succeed, @c nullptr otherwise. */ const Fill* strokeFill() const noexcept; /** * @brief Gets the dash pattern of the stroke. + * * @param[out] dashPattern The pointer to the memory, where the dash pattern array is stored. + * * @return The length of dash pattern array. */ uint32_t strokeDash(const float** dashPattern) const noexcept; /** * @brief Gets the cap style used for stroking the path. + * * @return The cap style value of the stroke. */ StrokeCap strokeCap() const noexcept; /** * @brief Gets the join style value used for stroking the path. + * * @return The join style value of the stroke. */ StrokeJoin strokeJoin() const noexcept; /** * @brief Creates a new Shape object. - * @return A unique pointer to the new Shape object. + * + * @return A new Shape object. */ static std::unique_ptr gen() noexcept; @@ -846,10 +941,10 @@ public: /** * @class Picture * - * @brief A 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. + * @brief A class representing an image read in one of the supported formats: raw, svg, png and etc. + * Besides the methods inherited from the Paint, it provides eaiser methods to load & draw images on the canvas. * + * @note Supported formats are depended on the available TVG loaders. */ class TVG_EXPORT Picture final : public Paint { @@ -857,75 +952,44 @@ public: ~Picture(); /** - * @brief Loads a picture data from a file. - * - * The direct loading from a file is available for the svg and png files. + * @brief Loads a picture data from a file directly. * * @param[in] path A path to the picture file. - * @retval Result::Success When succeeded. - * @retval Result::InvalidArguments In case the @p path is empty. - * @retval Result::NonSupport When trying to load a file with an unknown extension. - * @retval Result::Unknown If an error occurs at a later stage. - */ - Result load(const std::string& path) noexcept; - - /** - * @brief Loads a picture data from a memory block of a given size. * - * This method of data loading is supported only for the svg files. + * @retval @c Result::Success when succeed. + * @retval @c Result::InvalidArguments In case the @p path is empty. + * @retval @c Result::NonSupport When trying to load a file with an unknown extension. + * @retval @c Result::Unknown If an error occurs at a later stage. * - * @param[in] data A pointer to a memory location where the content of the svg file is stored. - * @param[in] size The size in bytes of the memory occupied by the @p data. - * @retval Result::Success When succeeded. - * @retval Result::InvalidArguments In case no data are provided or the @p size is zero or less. - * @retval Result::NonSupport When trying to load a file with an unknown extension. - * @retval Result::Unknown If an error occurs at a later stage. + * @note loading behavior could be asynchronous by thread option. */ - Result load(const char* data, uint32_t size) noexcept; + Result load(const std::string& path) noexcept; /** * @brief Loads a picture data from a memory block of a given size. * - * This method of data loading is supported only for the raw image format. - * - * @param[in] data The contiguous memory block of a size of w x h with the pixels information. - * @param[in] w The width of the image in pixels. - * @param[in] h The height of the image in pixels. - * @param[in] copy Specifies the method of copying the @p data - shallow if @c false and deep id @c true. - * @retval Result::Success When succeeded. - * @retval Result::InvalidArguments In case no data is provided or the width or the height of the picture is zero or less. - * @retval Result::NonSupport When trying to load a file with an unknown extension. - */ - Result load(uint32_t* data, uint32_t w, uint32_t h, bool copy) noexcept; - - /** - * @brief Gets the position and the size of the loaded picture. + * @param[in] data A pointer to a memory location where the content of the picture file is stored. + * @param[in] size The size in bytes of the memory occupied by the @p data. * - * For the svg file the returned values are specified in the viewBox attribute. - * For the png and raw files, @p x and @p y are zeros and @p w and @p h indicate the width - * and the height of the picture, respectively. + * @retval @c Result::Success when succeed. + * @retval @c Result::InvalidArguments In case no data are provided or the @p size is zero or less. + * @retval @c Result::NonSupport When trying to load a file with an unknown extension. + * @retval @c Result::Unknown If an error occurs at a later stage. * - * @param[out] x The horizontal coordinate of the upper left corner of the picture. - * @param[out] y The vertical coordinate of the upper left corner of the picture. - * @param[out] w The picture width. - * @param[out] h The picture height. - * @return Result::Success when succeeded, Result::InsufficientCondition otherwise. + * @note: This api supports only SVG format */ - //TODO: Replace with size(). Remove API - Result viewbox(float* x, float* y, float* w, float* h) const noexcept; + Result load(const char* data, uint32_t size) noexcept; /** - * @brief Sets a new size of the image. + * @brief Resize the picture content with the given width and height. * - * The functionality works only for the images loaded from svg files. - * The preserveAspectRatio attribute specified in the svg file determines whether the aspect ratio is preserved during the resizing. - * In case the preserving needs to be forced, - * the scaling factor is established for each of the-dimensions and the smaller value is applied - * to both of them. + * Resize the picture content while keeping the default size aspect ratio. + * The scaling factor is established for each of dimensions and the smaller value is applied to both of them. * * @param[in] w A new width of the image in pixels. * @param[in] h A new height of the image in pixels. - * @return Result::Success when succeeded, Result::InsufficientCondition otherwise. + * + * @return @c Result::Success when succeed, @c Result::InsufficientCondition otherwise. */ Result size(float w, float h) noexcept; @@ -933,22 +997,36 @@ public: * @brief Gets the size of the image. * @param[out] w The width of the image in pixels. * @param[out] h The height of the image in pixels. - * @return Result::Success. + * + * @return @c Result::Success when succeed. */ Result size(float* w, float* h) const noexcept; /** - * @brief Gets the pixels information of the image. - * - * The option is available for png and raw file formats. + * @brief Gets the pixels information of the picture. (BETA version) * - * @return A pointer to the memory location where the image data are stored when succeeded, @p nullptr otherwise. + * @warning Please do not use it, this API is not official one. It could be modified in the next version. */ const uint32_t* data() const noexcept; /** + * @brief Loads a raw data from a memory block with a given size. (BETA version) + * + * @warning Please do not use it, this API is not official one. It could be modified in the next version. + */ + Result load(uint32_t* data, uint32_t w, uint32_t h, bool copy) noexcept; + + /** + * @brief Gets the position and the size of the loaded picture. (BETA version) + * + * @warning Please do not use it, this API is not official one. It could be modified in the next version. + */ + Result viewbox(float* x, float* y, float* w, float* h) const noexcept; + + /** * @brief Creates a new Picture object. - * @return A unique pointer to the new Picture object. + * + * @return A new Picture object. */ static std::unique_ptr gen() noexcept; @@ -959,11 +1037,13 @@ public: /** * @class Scene * - * @brief A class enabling to hold many Paint objects. + * @brief A class to composite children paints. * - * 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. + * As the traditional graphics rendering method, TVG also enables scene-graph mechanism, + * This feature supports an array function for managing the multiple paints as one group paint. * + * As a group, scene can be transformed, translucent, composited with other target paints, + * its children will be affected by the scene world. */ class TVG_EXPORT Scene final : public Paint { @@ -971,12 +1051,17 @@ public: ~Scene(); /** - * @brief Passes the Paint object to the Scene. + * @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 count of push() in the advance, please call Scene::reserve(). * - * The function may be called many times and all passed objects will be rendered. + * @param[in] paint A Paint object to be drawn. * - * @param[in] paint A unique pointer to the Paint object. - * @return Result::Success when succeeded, Result::MemoryCorruption otherwise. + * @return @c Result::Success when succeed, @c Result::MemoryCorruption otherwise. + * + * @note Rendering order of the paints are in the order of the push. Thus if you mind a layering, sorting the paints before pushing them. */ Result push(std::unique_ptr paint) noexcept; @@ -987,22 +1072,22 @@ public: * prevents multiple memory reallocation, thus improving the performance. * * @param[in] size The number of objects for which the memory is to be reserved. - * @return Result::Success. + * + * @return @c Result::Success. */ Result reserve(uint32_t size) noexcept; /** - * @brief Sets the total number of the paints pushed into the scene to be zero. + * @brief Sets the total number of the paints pushed into the scene to be zero. (BETA version) * - * The memory is not deallocated at this stage. - * - * @return Result::Success. + * @warning Please do not use it, this API is not official one. It could be modified in the next version. */ Result clear() noexcept; /** * @brief Creates a new Scene object. - * @return A unique pointer to the new Scene object. + * + * @return A new Scene object. */ static std::unique_ptr gen() noexcept; @@ -1013,8 +1098,7 @@ public: /** * @class SwCanvas * - * @brief A class for the rasterisation of graphic elements with a software engine. - * + * @brief A class for the rendering graphic elements with a software raster engine. */ class TVG_EXPORT SwCanvas final : public Canvas { @@ -1031,25 +1115,28 @@ public: }; /** - * @brief Sets the target of the rasterisation. + * @brief Sets the target buffer for the rasterization. * - * The buffer of a desirable size should be already allocated. + * The buffer of a desirable size should be allocated and owned by the caller. * * @param[in] buffer A pointer to a memory block of the size @p w x @p h, where the raster data are stored. * @param[in] stride The stride of the raster image - greater than or equal to @p w. * @param[in] w The width of the raster image. * @param[in] h The height of the raster image. * @param[in] cs The value specifying the way the 32-bits colors should be read/written. - * @retval Result::Success when succeeded. - * @retval Result::MemoryCorruption When casting in the internal function implementation failed. - * @retval Result::InvalidArguments In case no valid pointer is provided or the width, or the height or the stride is zero. - * @retval Result::NonSupport In case the software engine is not enabled in the 'meson_options.txt' file. - */ + * + * @retval @c Result::Success when succeed. + * @retval @c Result::MemoryCorruption When casting in the internal function implementation failed. + * @retval @c Result::InvalidArguments In case no valid pointer is provided or the width, or the height or the stride is zero. + * @retval @c Result::NonSupport In case the software engine is not supported. + * + * @warning Do not access @p buffer during Canvas::draw() - Canvas::sync(). It should not be accessed while TVG is writing on it. + */ Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h, Colorspace cs) noexcept; /** * @brief Creates a new SwCanvas object. - * @return A unique pointer to the new SwCanvas object when succeeded, @c nullptr if the software engine is not enabled in the 'meson_options.txt' file. + * @return A new SwCanvas object when succeed, otherwise @c nullptr */ static std::unique_ptr gen() noexcept; @@ -1058,10 +1145,11 @@ public: /** - * @class GlCanvas + * @class GlCanvas (BETA version) * - * @brief A class for the rasterisation of graphic elements with the OpenGL engine. + * @brief A class for the rendering graphic elements with a GL raster engine. * + * @warning Please do not use it, This class is not fully supported yet. */ class TVG_EXPORT GlCanvas final : public Canvas { @@ -1069,14 +1157,16 @@ public: ~GlCanvas(); /** - * @brief Sets the target of the rasterisation. + * @brief Sets the target buffer for the rasterization. (BETA version) + * + * @warning Please do not use it, this API is not official one. It could be modified in the next version. */ - //TODO: Gl Specific methods. Need gl backend configuration methods as well. Result target(uint32_t* buffer, uint32_t stride, uint32_t w, uint32_t h) noexcept; /** - * @brief Creates a new GlCanvas object. - * @return A unique pointer to the new GlCanvas object when succeeded, @c nullptr if the OpenGL engine is not enabled in the 'meson_options.txt' file. + * @brief Creates a new GlCanvas object.(BETA version) + * + * @return A new GlCanvas object when succeed, otherwise @c nullptr */ static std::unique_ptr gen() noexcept; @@ -1087,32 +1177,46 @@ public: /** * @class Initializer * - * @brief A class that enables initialization and termination of the ThorVG engine. - * + * @brief A class that enables initialization and termination of the TVG engines. */ class TVG_EXPORT Initializer final { public: /** - * @brief Initializes the ThorVG engine. - * @param[in] engine The engine type - the same as specified in the 'meson_options.txt' file. - * @param[in] threads The number of threads - zero is treated as one. - * @retval Result::Success When succeeded. - * @retval Result::InsufficientCondition An internal error possibly with memory allocation. - * @retval Result::InvalidArguments If unknown engine type chosen. - * @retval Result::NonSupport In case the engine type in the 'meson_options.txt' differs from the one specified in the @p engine argument. - * @retval Result::Unknown Other. + * @brief Initializes TVG engines. + * + * TVG requires the running-engine environment. + * Basically TVG runs its own task-scheduler for parallelizing rendering tasks efficiently. + * For the benefits, you can indicates threads numbers which count is designated TVG threads. + * In the initialization step, TVG will generate/spawn the threads by @p threads count. + * + * @param[in] engine The engine types to initialize. This is relative to Canvas types which will be used in. For multiple backeneds, Bitwise operation is allowed + * @param[in] threads The number of additional threads. Zero indiciates the main thread. + * + * @retval @c Result::Success when succeed. + * @retval @c Result::InsufficientCondition An internal error possibly with memory allocation. + * @retval @c Result::InvalidArguments If unknown engine type chosen. + * @retval @c Result::NonSupport In case the engine type is not supported on the system. + * @retval @c Result::Unknown Others. + * + * @note Initialilzer does own reference counting for multiple calls. Threads count will be fixed at the first init() call. + * @see Initializer::term() */ static Result init(CanvasEngine engine, uint32_t threads) noexcept; /** - * @brief Terminates the ThorVG engine. - * @param[in] engine The engine type - the same as specified in the 'meson_options.txt' file. - * @retval Result::Success When succeeded. - * @retval Result::InsufficientCondition In case there is nothing to be terminated. - * @retval Result::InvalidArguments If unknown engine type chosen. - * @retval Result::NonSupport In case the engine type in the 'meson_options.txt' differs from the one specified in the @p engine argument. - * @retval Result::Unknown Other. + * @brief Terminates TVG engines. + * + * @param[in] engine The engine types to terminate. This is relative to Canvas types which will be used in. For multiple backeneds, Bitwise operation is allowed + * + * @retval @c Result::Success when succeed. + * @retval @c Result::InsufficientCondition In case there is nothing to be terminated. + * @retval @c Result::InvalidArguments If unknown engine type chosen. + * @retval @c Result::NonSupportt In case the engine type is not supported on the system. + * @retval @c Result::Unknown Others. + * + * @note Initialilzer does own reference counting for multiple calls. + * @see Initializer::init() */ static Result term(CanvasEngine engine) noexcept; diff --git a/inc/thorvg_capi.h b/inc/thorvg_capi.h index 9555c3f..7976850 100644 --- a/inc/thorvg_capi.h +++ b/inc/thorvg_capi.h @@ -1,6 +1,6 @@ /*! * \file thorvg_capi.h -* \brief Function provides C bindings for thorvg library. +* \brief Function provides C bindings for thorvg library. (BETA version) * Please refer to src/examples/Capi.cpp to find thorvg_capi examples. * * thorvg_capi module provides a set of functionality that allows to @@ -39,8 +39,8 @@ typedef struct _Tvg_Paint Tvg_Paint; typedef struct _Tvg_Gradient Tvg_Gradient; /** -* \defgroup ThorVGCapi C APIs -* \brief ThorVG provides C interface. +* \defgroup ThorVG_CAPI (BETA version) +* \brief ThorVG C Language Binding APIs. * * \{ */ -- 2.7.4 From d208b82bc868b25b9cc920ec3d552e10d048ac07 Mon Sep 17 00:00:00 2001 From: Hermet Park Date: Fri, 30 Apr 2021 19:02:06 +0900 Subject: [PATCH 14/16] infra: disable capi in default. capi is not mandatory option in v0.1. we can manually toggle it on when it's necessary. Change-Id: If76d310b411e27129b2bf2a3c728872b305b6b4b --- meson_options.txt | 2 +- src/examples/meson.build | 22 ++++++++++++++++++---- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/meson_options.txt b/meson_options.txt index f7fcc72..d517110 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -19,7 +19,7 @@ option('vectors', option('bindings', type: 'array', choices: ['', 'capi'], - value: ['capi'], + value: [''], description: 'Enable C API binding') option('tools', diff --git a/src/examples/meson.build b/src/examples/meson.build index a1dc12b..6ce0cb1 100644 --- a/src/examples/meson.build +++ b/src/examples/meson.build @@ -5,7 +5,6 @@ source_file = [ 'Async.cpp', 'Blending.cpp', 'Boundary.cpp', - 'Capi.cpp', 'CustomTransform.cpp', 'DirectUpdate.cpp', 'Duplicate.cpp', @@ -42,7 +41,22 @@ source_file = [ foreach current_file : source_file name = current_file.split('.')[0] executable(name, current_file, - include_directories : headers, - link_with : thorvg_lib, - dependencies : examples_dep) + include_directories : headers, + link_with : thorvg_lib, + dependencies : examples_dep) endforeach + + +if get_option('bindings').contains('capi') == true + capi_source_file = [ + 'Capi.cpp' + ] + + foreach current_file : capi_source_file + name = current_file.split('.')[0] + executable(name, current_file, + include_directories : headers, + link_with : thorvg_lib, + dependencies : examples_dep) + endforeach +endif -- 2.7.4 From 53963454a8c95173f83acb429a83789103b6d907 Mon Sep 17 00:00:00 2001 From: Hermet Park Date: Fri, 30 Apr 2021 19:33:17 +0900 Subject: [PATCH 15/16] enable capi binding in tizen. Tizen needs to use capi for efl integration. Change-Id: I238e416c9397a6596ae0e028a304569411baefee --- meson_options.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/meson_options.txt b/meson_options.txt index d517110..f7fcc72 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -19,7 +19,7 @@ option('vectors', option('bindings', type: 'array', choices: ['', 'capi'], - value: [''], + value: ['capi'], description: 'Enable C API binding') option('tools', -- 2.7.4 From 9e95ef600370aad9cfc1406e2d42c305f8756792 Mon Sep 17 00:00:00 2001 From: Hermet Park Date: Fri, 30 Apr 2021 19:45:22 +0900 Subject: [PATCH 16/16] bump up v0.1.4 Change-Id: Id45999aba84a8a0fe992e2ba841650a229b2b2a7 --- packaging/thorvg.spec | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packaging/thorvg.spec b/packaging/thorvg.spec index 792e13b..65b0138 100644 --- a/packaging/thorvg.spec +++ b/packaging/thorvg.spec @@ -1,6 +1,6 @@ Name: thorvg Summary: Thor Vector Graphics Library -Version: 0.1.3 +Version: 0.1.4 Release: 1 Group: Graphics System/Rendering Engine License: MIT -- 2.7.4