Shape 类 API 文档 - PA2D 图形库

文档概览

此文档详细介绍了 pa2d 库中的几何图形系统，包含基础几何结构、图形类继承体系、变换操作和样式系统。该模块提供面向对象的几何图形表示和操作能力。

主要分为三个核心模块：
Style 样式配置 - 控制图形的绘制样式，如颜色、线宽、圆角等
Shape 几何图形系统 - 包含所有几何图形类，从基础的 Point 到复杂的扇形
Path 路径构建器 - 提供链式操作创建复杂路径的工具

Style 样式配置

几何图形的绘制样式配置，支持流式接口和字面量语法。

Style 结构

属性	类型	设置方法	默认值	说明
fill_	`Color`	`fill(Color)`	`0`	填充颜色
stroke_	`Color`	`stroke(Color)`	`0`	描边颜色
width_	`float`	`width(float)`	`1.0f`	线宽
radius_	`float`	`radius(float)`	`0.0f`	圆角半径
arc_	`bool`	`arc(bool)`	`true`	是否绘制圆弧（扇形）
edges_	`bool`	`edges(bool)`	`true`	是否绘制边（扇形）

字面量语法

使用用户定义字面量创建样式，需要包含头文件且未定义 PA2D_DISABLE_LITERALS。

字面量	类型	示例	说明
颜色字面量	`FillTag`	`0xFFFF0000_fill` `"#FF0000"_fill`	填充颜色，支持十六进制或CSS颜色字符串
颜色字面量	`StrokeTag`	`0xFF00FF00_stroke` `"#00FF00"_stroke`	描边颜色
线宽字面量	`WidthTag`	`2.0_w` `5_w`	线宽，支持浮点和整数
半径字面量	`RadiusTag`	`10.5_r` `8_r`	圆角半径
预定义样式	`Style`	`pa2d::arc` `pa2d::no_arc`	圆弧控制标志
预定义样式	`Style`	`pa2d::edges` `pa2d::no_edges`	边控制标志
预定义颜色样式	`Style`	`pa2d::Red_fill` `pa2d::Blue_stroke`	预定义颜色的填充/描边样式

Shape 几何图形系统

包含所有几何图形类的完整系统，从基础的点结构到复杂的图形类。

Point 结构

基础二维点结构，是所有图形的基础。

方法	说明
`Point()` `Point(float x, float y)`	构造函数
`float x`, `float y`	公共成员变量，可直接访问
`operator+`, `operator-`, `operator*`, `operator/`	支持点与点、点与标量的所有算术运算
`operator+=`, `operator-=`, `operator*=`, `operator/=`	复合赋值运算
`operator==`, `operator!=`	相等性比较
`translate(float dx, float dy)`	平移变换
`scale(float scale)` `scale(float scaleX, float scaleY)`	缩放变换(基于原点)
`rotate(float angle, float centerX = 0, float centerY = 0)`	旋转变换（centerX/Y默认0，基于原点）
`friend Point operator*(float scalar, const Point& point)`	标量在前乘法的友元函数

Shape 抽象基类

所有几何图形的基类，定义统一接口。所有具体图形类都继承自此类。

方法	说明
`GeometryType getType() const`	获取几何类型枚举值
`Shape& translate(float dx, float dy)`	相对平移变换
`Shape& translate(Point delta)`	使用点向量平移
`Shape& scale(float factor)`	等比例缩放（绕原点）
`Shape& scale(float factorX, float factorY)`	非均匀缩放（绕原点）
`Shape& scaleOnSelf(float factor)`	以自身为中心等比例缩放
`Shape& scaleOnSelf(float factorX, float factorY)`	以自身为中心非均匀缩放
`Shape& rotate(float angle)`	绕原点旋转
`Shape& rotate(float angle, float centerX, float centerY)`	绕指定点旋转
`Shape& rotate(float angle, Point center)`	绕指定点旋转
`Shape& rotateOnSelf(float angle)`	以自身为中心旋转
`bool contains(Point point) const`	判断点是否在图形内
`Rect getBoundingBox() const`	获取边界框（返回 Rect 对象）
`Point getCenter() const`	获取中心点

Points 类

点集合，继承自 Shape，内部使用 std::vector<Point> 存储点。

方法	说明
`Points()`	创建空点集
`Points(int size)`	创建指定数量点集（默认构造的点）
`Points(std::vector<Point>& points)`	从向量构造（引用）
`std::vector<Point> points`	点数据存储（公开访问）

Line 类

直线段，由起点和终点定义。

方法	说明
`Line()`	默认构造，起点终点为(0,0)
`Line(float x0, float y0, float x1, float y1)`	坐标构造
`Line(const Point& start, const Point& end)`	点构造
`Line& start(float x, float y)`	设置起点坐标
`Line& start(const Point& start)`	设置起点
`Line& end(float x, float y)`	设置终点坐标
`Line& end(const Point& end)`	设置终点
`Point& start()`	获取起点引用
`Point start() const`	获取起点值
`Point& end()`	获取终点引用
`Point end() const`	获取终点值
`operator std::vector<Point>() const`	转换为点向量[起点, 终点]

Polygon 类

多边形，内部使用 Points 存储顶点。

方法	说明
`Polygon()`	默认构造
`Polygon(const std::vector<Point>& points)`	从点集构造
`std::vector<Point>& getPoints()`	获取顶点集合引用
`const std::vector<Point>& getPoints() const`	获取顶点集合常量引用
`Polygon& operator=(const std::vector<Point>& vec)`	从点向量赋值
`operator std::vector<Point>() const`	转换为点向量
`operator const std::vector<Point>&() const`	转换为点向量常量引用

Rect 类

矩形，支持旋转和中心点操作，内部缓存顶点以提高性能。

方法	说明
`Rect()`	默认构造，中心(0,0)，宽高0，不旋转
`Rect(float centerX, float centerY, float width, float height, float rotation = 0.0f)`	中心点构造
`Rect(const std::vector<Point>& points)`	从4个顶点构造（按顺序：左上、右上、右下、左下）
`Rect& center(const Point& center)`	设置中心点
`Rect& center(float x, float y)`	设置中心坐标
`Rect& width(float width)`	设置宽度
`Rect& height(float height)`	设置高度
`Rect& rotation(float rotation)`	设置旋转角度（度）
`Point center() const`	获取中心点
`float width() const`	获取宽度
`float height() const`	获取高度
`float rotation() const`	获取旋转角度
`begin()` `end()`	获取迭代器，遍历4个顶点
`Point& operator[](size_t index)`	通过索引访问顶点（0-3）
`Rect& operator=(const std::vector<Point>& points)`	从点向量赋值
`operator std::vector<Point>() const`	转换为点向量（4个顶点）

Triangle 类

三角形，由三个顶点定义。

方法	说明
`Triangle()`	默认构造，三个顶点为(0,0)
`Triangle(const Point& p0, const Point& p1, const Point& p2)`	点构造
`Triangle(float x0, float y0, float x1, float y1, float x2, float y2)`	坐标构造
`Triangle(const std::vector<Point>& points)`	向量构造（必须恰好3个点）
`begin()` `end()`	获取迭代器，遍历3个顶点
`Point& operator[](size_t index)`	通过索引访问顶点（0-2）
`Triangle& operator=(const std::vector<Point>& points)`	从点向量赋值
`operator std::vector<Point>() const`	转换为点向量（3个顶点）

Circle 类

圆形，由中心和半径定义。

方法	说明
`Circle()`	默认构造，中心(0,0)，半径0
`Circle(float centerX, float centerY, float radius)`	坐标构造
`Circle(const Point& center, float radius)`	点构造
`Circle& x(float x)`	设置中心X坐标
`Circle& y(float y)`	设置中心Y坐标
`Circle& center(const Point& center)`	设置中心点
`Circle& center(float x, float y)`	设置中心坐标
`Circle& radius(float radius)`	设置半径
`float x() const`	获取中心X坐标
`float y() const`	获取中心Y坐标
`Point& center()`	获取中心点引用
`Point center() const`	获取中心点值
`float radius() const`	获取半径
`operator Point() const`	转换为点（获取中心点）

Elliptic 类

椭圆，支持旋转。

方法	说明
`Elliptic()`	默认构造，中心(0,0)，宽高0，不旋转
`Elliptic(float centerX, float centerY, float width, float height, float rotation = 0.0f)`	完整构造
`Elliptic& x(float x)`	设置中心X坐标
`Elliptic& y(float y)`	设置中心Y坐标
`Elliptic& center(const Point& center)`	设置中心点
`Elliptic& center(float x, float y)`	设置中心坐标
`Elliptic& width(float width)`	设置宽度（长轴直径）
`Elliptic& height(float height)`	设置高度（短轴直径）
`Elliptic& rotation(float rotation)`	设置旋转角度（度）
`float x() const`	获取中心X坐标
`float y() const`	获取中心Y坐标
`Point& center()`	获取中心点引用
`Point center() const`	获取中心点值
`float width() const`	获取宽度
`float height() const`	获取高度
`float rotation() const`	获取旋转角度
`operator Point() const`	转换为点（获取中心点）

Ray 类

射线，由起点、终点、长度和角度定义，支持动态操作。

方法	说明
`Ray()`	默认构造，起点终点为(0,0)
`Ray(float x1, float y1, float x2, float y2)`	两点坐标构造
`Ray(const Point& start, const Point& end)`	两点构造
`Ray(const Point& start, float length = 0.0f, float angle = 0.0f)`	极坐标构造
`Ray& start(float x, float y)`	设置起点坐标
`Ray& start(const Point& start)`	设置起点
`Ray& end(float x, float y)`	设置终点坐标
`Ray& end(const Point& end)`	设置终点
`Ray& angle(float angle)`	设置角度（度，0-360）
`Ray& length(float length)`	设置长度
`Point start() const`	获取起点
`Point end() const`	获取终点
`float length() const`	获取长度
`float angle() const`	获取角度
`Ray& toEnd()`	根据起点、长度、角度更新终点
`Ray& stretch(float factor)`	按比例拉伸长度
`Ray& spin(float angle)`	旋转指定角度
`operator std::vector<Point>() const`	转换为点向量[起点, 终点]

Sector 类

扇形，由中心、半径和角度范围定义。

方法	说明
`Sector()`	默认构造，中心(0,0)，半径0，角度0-360
`Sector(Point center, float radius, float startAngle = 0.0f, float endAngle = 360.0f)`	点构造
`Sector(float centerX, float centerY, float radius, float startAngle = 0.0f, float endAngle = 360.0f)`	坐标构造
`Sector& x(float x)`	设置中心X坐标
`Sector& y(float y)`	设置中心Y坐标
`Sector& center(const Point& center)`	设置中心点
`Sector& center(float x, float y)`	设置中心坐标
`Sector& radius(float radius)`	设置半径
`Sector& startAngle(float startAngle)`	设置起始角度（度）
`Sector& endAngle(float endAngle)`	设置结束角度（度）
`float x() const`	获取中心X坐标
`float y() const`	获取中心Y坐标
`Point& center()`	获取中心点引用
`Point center() const`	获取中心点值
`float radius() const`	获取半径
`float startAngle() const`	获取起始角度
`float endAngle() const`	获取结束角度
`operator Point() const`	转换为点（获取中心点）

Path 路径构建器

Path 类

路径构建工具，支持链式操作创建复杂路径，使用 Builder 模式。

方法	说明
`static Builder from(float x, float y)`	从坐标开始创建路径
`static Builder from(const Point& start)`	从点开始创建路径
`Builder&& move(float dx, float dy)&&`	相对移动（添加新点）
`Builder&& moveTo(float x, float y)&&`	绝对移动（添加新点）
`Builder&& translate(float dx, float dy)&&`	平移整个路径
`Builder&& scale(float scale)&&`	等比例缩放整个路径（绕原点）
`Builder&& scale(float scaleX, float scaleY)&&`	非均匀缩放整个路径（绕原点）
`Builder&& scaleOnSelf(float scale)&&`	以路径自身为中心等比例缩放
`Builder&& scaleOnSelf(float scaleX, float scaleY)&&`	以路径自身为中心非均匀缩放
`Builder&& rotate(float angle)&&`	绕原点旋转整个路径
`Builder&& rotate(float angle, float centerX, float centerY)&&`	绕指定点旋转整个路径
`Builder&& rotateOnSelf(float angle)&&`	以路径自身为中心旋转
`template<typename T> T to()&&`	转换为指定类型的几何对象
`template<typename T> operator T()&&`	隐式转换为几何对象（移动语义）
`template<typename T> operator T()&`	隐式转换为几何对象（复制语义）

Path 类示例

// 创建简单路径
pa2d::Polygon polygon = pa2d::Path::from(0, 0)
    .moveTo(100, 100)
    .move(50, 0)
    .move(0, 50);

Shape API