From 4b11fea32f751e25f572cf5e24a8829776812d81 Mon Sep 17 00:00:00 2001 From: Hermet Park Date: Wed, 9 Jul 2025 18:24:58 +0900 Subject: [PATCH] api: rename shape fill rule API for clarity Clarify the FillRule usage by associating it explicitly with color/gradient fills. C++ API * Result Shape::fill(FillRule r) -> Result Shape::fillRule(FillRule r) issue: https://github.com/thorvg/thorvg/issues/3116 --- examples/FillRule.cpp | 6 ++++-- inc/thorvg.h | 17 ++++++++++++----- src/bindings/capi/thorvg_capi.h | 14 ++++++++++---- src/bindings/capi/tvgCapi.cpp | 2 +- src/loaders/lottie/tvgLottieBuilder.cpp | 4 ++-- src/loaders/svg/tvgSvgSceneBuilder.cpp | 2 +- src/renderer/tvgShape.cpp | 2 +- src/renderer/tvgText.h | 2 +- test/testShape.cpp | 2 +- 9 files changed, 33 insertions(+), 18 deletions(-) diff --git a/examples/FillRule.cpp b/examples/FillRule.cpp index 59b84b46..63358d9e 100644 --- a/examples/FillRule.cpp +++ b/examples/FillRule.cpp @@ -41,7 +41,8 @@ struct UserExample : tvgexam::Example shape1->lineTo(80, 355); shape1->close(); shape1->fill(255, 255, 255); - shape1->fill(tvg::FillRule::NonZero); //Fill all winding shapes + // Use the NonZero fill rule: fills all areas enclosed by paths with non-zero winding numbers + shape1->fillRule(tvg::FillRule::NonZero); canvas->push(shape1); @@ -54,7 +55,8 @@ struct UserExample : tvgexam::Example shape2->lineTo(410, 655); shape2->close(); shape2->fill(255, 255, 255); - shape2->fill(tvg::FillRule::EvenOdd); //Fill polygons with even odd pattern + // Use the EvenOdd fill rule: fills areas where path overlaps an odd number of times + shape2->fillRule(tvg::FillRule::EvenOdd); canvas->push(shape2); diff --git a/inc/thorvg.h b/inc/thorvg.h index 25231ce1..9dd03f54 100644 --- a/inc/thorvg.h +++ b/inc/thorvg.h @@ -1181,11 +1181,14 @@ public: Result fill(Fill* f) noexcept; /** - * @brief Sets the fill rule for the Shape object. + * @brief Sets the fill rule for the shape. * - * @param[in] r The fill rule value. The default value is @c FillRule::NonZero. + * Specifies how the interior of the shape is determined when its path intersects itself. + * The default fill rule is @c FillRule::NonZero. + * + * @param[in] r The fill rule to apply to the shape. */ - Result fill(FillRule r) noexcept; + Result fillRule(FillRule r) noexcept; /** * @brief Sets the rendering order of the stroke and the fill. @@ -1232,9 +1235,13 @@ public: Result fill(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a = nullptr) const noexcept; /** - * @brief Gets the fill rule value. + * @brief Retrieves the current fill rule used by the shape. * - * @return The fill rule value of the shape. + * This function returns the fill rule, which determines how the interior + * regions of the shape are calculated when it overlaps itself. + * + * @see Shape::fillRule(FillRule r) + * @return The current FillRule value of the shape. */ FillRule fillRule() const noexcept; diff --git a/src/bindings/capi/thorvg_capi.h b/src/bindings/capi/thorvg_capi.h index 207e5a33..ef743286 100644 --- a/src/bindings/capi/thorvg_capi.h +++ b/src/bindings/capi/thorvg_capi.h @@ -1468,10 +1468,13 @@ TVG_API Tvg_Result tvg_shape_get_fill_color(const Tvg_Paint* paint, uint8_t* r, /*! -* @brief Sets the shape's fill rule. +* @brief Sets the fill rule for the shape. +* +* Specifies how the interior of the shape is determined when its path intersects itself. +* The default fill rule is @c TVG_FILL_RULE_NON_ZERO. * * @param[in] paint A Tvg_Paint pointer to the shape object. -* @param[in] rule The fill rule value. The default value is @c TVG_FILL_RULE_NON_ZERO. +* @param[in] rule The fill rule to apply to the shape. * * @return Tvg_Result enumeration. * @retval TVG_RESULT_INVALID_ARGUMENT An invalid Tvg_Paint pointer. @@ -1480,10 +1483,13 @@ TVG_API Tvg_Result tvg_shape_set_fill_rule(Tvg_Paint* paint, Tvg_Fill_Rule rule) /*! -* @brief Gets the shape's fill rule. +* @brief Retrieves the current fill rule used by the shape. +* +* This function returns the fill rule, which determines how the interior +* regions of the shape are calculated when it overlaps itself. * * @param[in] paint A Tvg_Paint pointer to the shape object. -* @param[out] rule shape's fill rule +* @param[out] rule The current Tvg_Fill_Rule value of the shape. * * @return Tvg_Result enumeration. * @retval TVG_RESULT_INVALID_ARGUMENT An invalid pointer passed as an argument. diff --git a/src/bindings/capi/tvgCapi.cpp b/src/bindings/capi/tvgCapi.cpp index 737b95e1..552534b8 100644 --- a/src/bindings/capi/tvgCapi.cpp +++ b/src/bindings/capi/tvgCapi.cpp @@ -535,7 +535,7 @@ TVG_API Tvg_Result tvg_shape_get_fill_color(const Tvg_Paint* paint, uint8_t* r, TVG_API Tvg_Result tvg_shape_set_fill_rule(Tvg_Paint* paint, Tvg_Fill_Rule rule) { - if (paint) return (Tvg_Result) reinterpret_cast(paint)->fill((FillRule)rule); + if (paint) return (Tvg_Result) reinterpret_cast(paint)->fillRule((FillRule)rule); return TVG_RESULT_INVALID_ARGUMENT; } diff --git a/src/loaders/lottie/tvgLottieBuilder.cpp b/src/loaders/lottie/tvgLottieBuilder.cpp index 838f429b..e9b775e2 100644 --- a/src/loaders/lottie/tvgLottieBuilder.cpp +++ b/src/loaders/lottie/tvgLottieBuilder.cpp @@ -297,7 +297,7 @@ bool LottieBuilder::updateSolidFill(LottieGroup* parent, LottieObject** child, f ctx->merging = nullptr; auto color = fill->color(frameNo, tween, exps); ctx->propagator->fill(color.rgb[0], color.rgb[1], color.rgb[2], opacity); - ctx->propagator->fill(fill->rule); + ctx->propagator->fillRule(fill->rule); if (ctx->propagator->strokeWidth() > 0) ctx->propagator->order(true); @@ -318,7 +318,7 @@ bool LottieBuilder::updateGradientFill(LottieGroup* parent, LottieObject** child ctx->merging = nullptr; if (auto val = fill->fill(frameNo, opacity, tween, exps)) ctx->propagator->fill(val); - ctx->propagator->fill(fill->rule); + ctx->propagator->fillRule(fill->rule); if (ctx->propagator->strokeWidth() > 0) ctx->propagator->order(true); diff --git a/src/loaders/svg/tvgSvgSceneBuilder.cpp b/src/loaders/svg/tvgSvgSceneBuilder.cpp index 616d2a5f..40c4a4db 100644 --- a/src/loaders/svg/tvgSvgSceneBuilder.cpp +++ b/src/loaders/svg/tvgSvgSceneBuilder.cpp @@ -409,7 +409,7 @@ static Paint* _applyProperty(SvgLoaderData& loaderData, SvgNode* node, Shape* vg vg->fill(style->fill.paint.color.r, style->fill.paint.color.g, style->fill.paint.color.b, style->fill.opacity); } - vg->fill(style->fill.fillRule); + vg->fillRule(style->fill.fillRule); vg->order(!style->paintOrder); vg->opacity(style->opacity); diff --git a/src/renderer/tvgShape.cpp b/src/renderer/tvgShape.cpp index db6baf98..aacebd27 100644 --- a/src/renderer/tvgShape.cpp +++ b/src/renderer/tvgShape.cpp @@ -235,7 +235,7 @@ Result Shape::trimpath(float begin, float end, bool simultaneous) noexcept } -Result Shape::fill(FillRule r) noexcept +Result Shape::fillRule(FillRule r) noexcept { SHAPE(this)->rs.rule = r; return Result::Success; diff --git a/src/renderer/tvgText.h b/src/renderer/tvgText.h index db4b3aa1..6cbbaf11 100644 --- a/src/renderer/tvgText.h +++ b/src/renderer/tvgText.h @@ -45,7 +45,7 @@ struct TextImpl : Text TextImpl() : impl(Paint::Impl(this)), shape(Shape::gen()) { PAINT(shape)->parent = this; - shape->fill(FillRule::EvenOdd); + shape->fillRule(FillRule::EvenOdd); } ~TextImpl() diff --git a/test/testShape.cpp b/test/testShape.cpp index 20e84753..ee67c096 100644 --- a/test/testShape.cpp +++ b/test/testShape.cpp @@ -229,6 +229,6 @@ TEST_CASE("Shape Filling", "[tvgShape]") //Fill Rule REQUIRE(shape->fillRule() == FillRule::NonZero); - REQUIRE(shape->fill(FillRule::EvenOdd) == Result::Success); + REQUIRE(shape->fillRule(FillRule::EvenOdd) == Result::Success); REQUIRE(shape->fillRule() == FillRule::EvenOdd); }