开源图形库Thor Vector Graphics：Fill、RadialGradient、LinearGradient类 ，FillRule、FillSpread枚举类型 ColorStop 结构体

0. 简介

0.1 Fill

Fill是一个抽象类，表示形状对象的渐变填充。它包含有关渐变颜色及其在渐变范围内的排列方式的信息。渐变范围在线性渐变或径向渐变类中定义，具体取决于要使用的渐变类型。它指定了渐变边界定义的区域小于要填充的区域时的渐变行为。

0.2

0.3

1. 类

1.1 Fill成员函数

• Result colorStops(const ColorStop* colorStops, uint32_t cnt) noexcept：设置渐变颜色及其位置的参数。
  • 使用方法：传入一个ColorStop数组以及数组的长度，表示颜色及其相对位置。
  • 注意事项：确保传入的颜色停止点按照位置从小到大排序。
• Result spread(FillSpread s) noexcept：设置渐变范围外部填充区域的填充方式。
  • 使用方法：传入一个FillSpread枚举值，指定填充方式。
  • 注意事项：填充方式包括Pad、Reflect和Repeat，具体含义取决于枚举值的定义。
• Result transform(const Matrix& m) noexcept：设置渐变填充的仿射变换矩阵。
  • 使用方法：传入一个 3x3 的增广矩阵 m。
  • 注意事项：确保传入的矩阵是有效的仿射变换矩阵。
• uint32_t colorStops(const ColorStop** colorStops) const noexcept：获取渐变的颜色、位置和数量的参数。
  • 使用方法：传入一个ColorStop指针的指针，用于存储颜色停止点数组。
  • 返回值：返回颜色的数量，对应于colorStops数组的长度。
• FillSpread spread() const noexcept：获取填充范围外部的填充方式。
  • 使用方法：直接调用该函数。
  • 返回值：返回一个FillSpread枚举值，表示填充方式。
• Matrix transform() const noexcept描述：获取渐变填充的仿射变换矩阵。
  • 使用方法：直接调用该函数。
  • 返回值：返回一个Matrix对象，表示仿射变换矩阵。
• Fill* duplicate() const noexcept：创建Fill对象的副本。
  • 使用方法：直接调用该函数。
  • 返回值：返回一个新创建的 Fill 对象，其属性与原始对象相同，如果失败则返回nullptr。
• uint32_t identifier() const noexcept：返回Fill实例的唯一标识符值。
  • 使用方法：通常用于检查当前具体实例的类型。
  • 返回值：返回Fill实例的类型标识符。

1.2 RadialGradient成员函数

RadialGradient是一个表示形状对象的径向渐变填充的类是Fill的子类。
使用场景：
当需要在形状对象上应用径向渐变填充时，可以使用此类。例如，绘制一个圆形或椭圆形，并使用径向渐变填充来创建立体效果或渐变色效果。
成员函数：

• Result radial(float cx, float cy, float radius) noexcept：设置径向渐变的边界。
  • 参数：
    • cx：圆心的水平坐标。
    • cy：圆心的垂直坐标。
      -radius：圆的半径。
  • 返回值：成功时返回 Result::Success，如果radius值为零或更小，则返回Result::InvalidArguments。
  • 注意事项：确保提供的半径值大于零。
• Result radial(float* cx, float* cy, float* radius) const noexcept：获取径向渐变的边界。
  • 参数：
    • cx：圆心的水平坐标（输出参数）。
    • cy：圆心的垂直坐标（输出参数）。
    • radius：圆的半径（输出参数）。
  • 返回值：成功时返回Result::Success。
  • 注意事项：确保传入非空指针，以便将获取的值写入。
• static std::unique_ptr<RadialGradient> gen() noexcept：创建一个新的RadialGradient对象。
  • 返回值：返回一个指向RadialGradient对象的std::unique_ptr。
  • 注意事项：调用此函数创建RadialGradient对象。
• static uint32_t identifier() noexcept`能：返回此类的唯一 id 值。
  • 返回值：RadialGradient类型的类型id。
  • 注意事项：可以用于识别RadialGradient类型。

1.3 LinearGradient类成员函数

LinearGradient表示形状对象的线性渐变填充的类，是Fill的子类。

成员函数：

• Result linear(float x1, float y1, float x2, float y2) noexcept：设置线性渐变的边界。
  • 参数：
    • x1：第一个点的水平坐标。
    • y1：第一个点的垂直坐标。
    • x2：第二个点的水平坐标。
    • y2：第二个点的垂直坐标。
  • 返回值：成功时返回 Result::Success。
  • 注意事项：确保提供的点不相等，否则渐变将无法渲染。
• Result linear(float* x1, float* y1, float* x2, float* y2) const noexcept：获取线性渐变的边界。
  • 参数：
    • x1：第一个点的水平坐标（输出参数）。
    • y1：第一个点的垂直坐标（输出参数）。
    • x2：第二个点的水平坐标（输出参数）。
    • y2：第二个点的垂直坐标（输出参数）。
  • 返回值：成功时返回Result::Success。
  • 注意事项：确保传入非空指针，以便将获取的值写入。
• static std::unique_ptr<LinearGradient> gen() noexcept：创建一个新的 LinearGradient 对象。
  • 返回值：返回一个指向 LinearGradient 对象的 std::unique_ptr。
  • 注意事项：调用此函数创建 LinearGradient 对象。
• static uint32_t identifier() noexcept：返回此类的唯一 id 值。
  • 返回值：LinearGradient类型的类型 id。
  • 注意事项：可以用于识别LinearGradient类型。

2.

2.1 FillRule 枚举类型

• Winding填充规则：
  • 当使用FillRule::Winding时，通过以下步骤来确定点是否在形状内部：
    1. 从该点向形状外部的某个位置绘制一条直线。
    2. 计算直线与形状路径段的交点。
    3. 如果路径段与直线的交叉点顺时针，则将交点数加一，否则减一。
    4. 如果最终的交点数不为零，则该点被视为在形状内部。
  • 注意事项：通常用于确定具有复杂路径的形状的内部。
• EvenOdd填充规则：
  • 当使用FillRule::EvenOdd时，通过以下步骤来确定点是否在形状内部：
    1. 从该点向形状外部的某个位置绘制一条直线。
    2. 计算直线与形状路径段的交点。
    3. 如果交点数是奇数，则该点被视为在形状内部，否则视为在外部。
  • 通常用于简单的形状，可以更快速地确定内部和外部。

2.2 FillSpread 枚举类型

FillSpread枚举指定了在渐变范围之外的区域如何进行填充。

• Pad：使用最近的停止颜色填充剩余区域。
• Reflect：在渐变区域之外反射渐变图案，直到填充期望的区域。
• Repeat：在渐变区域之外连续重复渐变图案，直到填充期望的区域。

2.2 ColorStop 结构体

ColorStop被定义在Fill类中，用于存储渐变颜色及其在渐变范围内的相对位置信息。

	/*Quoted from： https://github.com/thorvg/thorvg/blob/main/inc/thorvg.h*/
	
    struct ColorStop
    {
        float offset; /* 颜色的相对位置，范围在 0 到 1 之间。 */
        uint8_t r;    /* 红色通道的值，范围在 0 到 255 之间。 */
        uint8_t g;    /* 绿色通道的值，范围在 0 到 255 之间。 */
        uint8_t b;    /* 蓝色通道的值，范围在 0 到 255 之间。 */
        uint8_t a;    /* Alpha 通道的值，范围在 0 到 255 之间，其中 0 表示完全透明，255 表示完全不透明。 */
    };

• 使用方法：
  • 创建ColorStop对象并设置成员变量的值，表示一个颜色及其相对位置。
  • 将ColorStop对象添加到渐变的颜色停止点数组中，以便在渐变中使用。