开源图形库Thor Vector Graphics：Shape类 StrokeCap StrokeJoin枚举类型

0. 简介

Shape类提供了一组用于表示二维图形及其属性的方法。

1. 成员函数

• Result reset() noexcept：重置形状路径的属性。
  • 使用方法：调用该函数以重置形状路径的属性，但保留变换矩阵、颜色、填充和描边属性。
  • 注意事项：路径数据的内存不会在此阶段被释放，以提高性能。
• Result moveTo(float x, float y) noexcept：设置子路径的起始点。
  • 使用方法：传入起始点的水平和垂直坐标。
  • 注意事项：在路径中第一次调用此函数相当于调用 moveTo()。
• Result lineTo(float x, float y) noexcept：向子路径添加一个新点，绘制从当前点到给定结束点的直线。
  • 使用方法：传入直线的结束点的水平和垂直坐标。
  • 注意事项：如果这是路径中的第一个命令，则相当于调用 moveTo()。
• Result cubicTo(float cx1, float cy1, float cx2, float cy2, float x, float y) noexcept：向子路径添加新点，绘制从当前点到给定结束点的三次贝塞尔曲线。
  • 使用方法：传入三次贝塞尔曲线的控制点和结束点的水平和垂直坐标。
  • 注意事项：如果这是路径中的第一个命令，则不会渲染任何数据。
• Result close() noexcept：通过绘制一条线段从当前点到子路径的起始点来关闭当前子路径。
  • 使用方法：调用该函数来关闭当前子路径。
  • 注意事项：如果子路径不包含任何点，则此函数没有效果。
• Result appendRect(float x, float y, float w, float h, float rx = 0, float ry = 0) noexcept：向路径中添加一个矩形。
  • 使用方法：传入矩形的上左角坐标、宽度、高度以及圆角的 x 和 y 轴半径。
  • 注意事项：根据给定的圆角半径值，矩形可能会变成圆角矩形或椭圆。
• Result appendCircle(float cx, float cy, float rx, float ry) noexcept：向路径中添加一个椭圆。
  • 使用方法：传入椭圆的中心点坐标和 x、y 轴的半径。
  • 注意事项：添加的椭圆被视为一个新的子路径。
• Result appendArc(float cx, float cy, float radius, float startAngle, float sweep, bool pie) noexcept：向路径中添加一个圆弧。
  • 使用方法：传入圆弧的中心点坐标、半径、起始角度、扫描角度和是否绘制半径线的标志。
  • 注意事项：如果扫描角度大于 360 度，则等效于添加一个圆。
• Result appendPath(const PathCommand* cmds, uint32_t cmdCnt, const Point* pts, uint32_t ptsCnt) noexcept：将给定的子路径追加到路径中。
  • 使用方法：传入子路径的命令数组和点数组。
  • 注意事项：该接口设计用于在调用者已有完整路径命令时进行优化路径设置。
• Result strokeWidth(float width) noexcept：设置路径的描边宽度。
  • 使用方法：传入描边宽度的值。
  • 注意事项：默认值为 0。
• Result strokeFill(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255) noexcept：设置路径描边的颜色。
  • 使用方法：传入颜色的 RGB 和 alpha 通道值。
  • 注意事项：填充颜色或渐变填充的设置取决于最后设置的是什么。
• Result strokeFill(std::unique_ptr f) noexcept：设置路径描边的渐变填充。
  • 使用方法：传入渐变填充对象的唯一指针。
  • 注意事项：填充颜色或渐变填充的设置取决于最后设置的是什么。
• Result strokeDash(const float* dashPattern, uint32_t cnt, float offset = 0.0f) noexcept：设置路径描边的虚线模式。
  • 使用方法：传入连续一对值的虚线长度和间隙长度的数组以及可选的起始偏移量。
  • 注意事项：要重置描边的虚线模式，将 dashPattern 设为 nullptr，cnt 设为 0。
• Result strokeCap(StrokeCap cap) noexcept：设置路径描边的线帽样式。
  • 使用方法：传入线帽样式枚举值。
  • 注意事项：默认值为 StrokeCap::Square。
• Result strokeJoin(StrokeJoin join) noexcept：设置路径描边的线段连接样式。
  • 使用方法：传入线段连接样式枚举值。
  • 注意事项：默认值为 StrokeJoin::Bevel。
• Result strokeMiterlimit(float miterlimit) noexcept：设置路径描边的斜接限制。
  • 使用方法：传入斜接限制值。
  • 注意事项：默认值为 4。
• Result fill(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255) noexcept：设置路径填充的颜色。
  • 使用方法：传入颜色的RGB和alpha通道值。
  • 注意事项：填充颜色或渐变填充的设置取决于最后设置的是什么。
• Result fill(std::unique_ptr f) noexcept：设置路径填充的渐变填充。
  • 使用方法：传入渐变填充对象的唯一指针。
  • 注意事项：填充颜色或渐变填充的设置取决于最后设置的是什么。
• Result fill(FillRule r) noexcept：设置形状对象的填充规则。
  • 使用方法：传入填充规则枚举值。
  • 注意事项：默认值为 FillRule::Winding。
• Result order(bool strokeFirst) noexcept：设置描边和填充的渲染顺序。
  • 使用方法：传入 true 以在填充之前渲染描边，否则描边将作为第二个渲染对象（默认选项）。
  • 注意事项：这对于控制描边和填充的遮盖效果很有用。
• uint32_t pathCommands(const PathCommand** cmds) const noexcept：获取路径的命令数据。
  • 使用方法：传入命令数组的指针，用于接收路径的命令数据。
  • 返回值：成功时返回命令数组的长度，否则返回 0。
• uint32_t pathCoords(const Point** pts) const noexcept：获取路径的点坐标值。
  • 使用方法：传入点数组的指针，用于接收路径的点坐标数据。
  • 返回值：成功时返回点数组的长度，否则返回 0。
• const Fill* fill() const noexcept;
  • 功能：获取形状的渐变填充。
  • 返回值：成功时返回填充对象的指针，如果没有设置填充则返回 nullptr。
• Result fillColor(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a = nullptr) const noexcept：获取形状的填充颜色。
  • 使用方法：传入颜色通道的指针，用于接收填充颜色的 RGB 和 alpha 通道值。
  • 返回值：成功时返回 Result::Success。
• FillRule fillRule() const noexcept：获取形状的填充规则。
  • 返回值：填充规则的枚举值。
• float strokeWidth() const noexcept：获取路径描边的宽度。
  • 返回值：描边宽度的值，如果没有设置描边则返回 0。
• Result strokeFill(uint8_t* r, uint8_t* g, uint8_t* b, uint8_t* a = nullptr) const noexcept：获取路径描边的颜色。
  • 使用方法：传入颜色通道的指针，用于接收描边颜色的 RGB 和 alpha 通道值。
  • 返回值：成功时返回 Result::Success，如果没有设置描边则返回 Result::InsufficientCondition。
• const Fill* strokeFill() const noexcept：获取路径描边的渐变填充。
  • 返回值：成功时返回渐变填充对象的指针，如果没有设置渐变填充则返回 nullptr。
• uint32_t strokeDash(const float** dashPattern, float* offset = nullptr) const noexcept：获取路径描边的虚线模式。
  • 使用方法：传入虚线模式数组的指针以及可选的偏移量指针。
  • 返回值：虚线模式数组的长度。
• StrokeCap strokeCap() const noexcept：获取路径描边的线帽样式。
  • 返回值：线帽样式的枚举值。
• StrokeJoin strokeJoin() const noexcept：获取路径描边的线段连接样式。
  • 返回值：线段连接样式的枚举值。
• float strokeMiterlimit() const noexcept：获取路径描边的斜接限制。
  • 返回值：斜接限制的值，如果没有设置描边则返回默认值 4。
• static std::unique_ptr gen() noexcept：创建一个新的 Shape 对象。
  • 返回值：一个新的 Shape 对象的唯一指针。
• static uint32_t identifier() noexcept：返回该类的唯一标识符。
  • 返回值：Shape 类型的标识符。

1.1 StrokeCap 枚举类型

StrokeCap用于确定路径描边的线帽样式，即在开放子路径的结束点处确定描边的形状(确定路径描边的末端形状)。

• Square：描边以矩形方式延伸到子路径的两个端点，在矩形的宽度等于描边宽度，长度等于描边宽度的一半。对于长度为零的子路径，以描边宽度的大小渲染一个正方形。
• Round：描边以半圆方式延伸到子路径的两个端点，半径等于描边宽度的一半。对于长度为零的子路径，渲染一个完整的圆。
• Butt：描边准确地结束在子路径的两个端点处。对于长度为零的子路径，不渲染描边。

1.2 StrokeJoin 枚举类型

StrokeJoin 是一个枚举类型，用于确定连接的描边路径段的角落样式。

• Bevel：连接的路径段的外部角落被斜切（斜角）在连接点处。角落的三角形区域由每个描边的外部角的直线封闭。
• Round：连接的路径段的外部角落是圆角的。圆角区域以连接点为中心。
• Miter：连接的路径段的外部角落是尖锐的。通过延伸描边的外缘直到它们相交来创建尖锐的尖端。如果延伸超出限制，连接样式将转换为 Bevel 样式。