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

@@ -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);
 

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;
 

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.

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<Shape*>(paint)->fill((FillRule)rule);
+    if (paint) return (Tvg_Result) reinterpret_cast<Shape*>(paint)->fillRule((FillRule)rule);
     return TVG_RESULT_INVALID_ARGUMENT;
 }
 

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);
 

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);
 

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;

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()

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);
 }