ViewDesignEngine/docs/02-概要设计/03-接口定义.md

接口定义

目录

1. 命名约定
2. 核心接口抽象
   • 2.1 空间索引接口
   • 2.2 曲线求值接口
   • 2.3 网格数据结构接口
   • 2.4 布尔运算接口
3. 稳定 C API（可选）
4. 错误处理约定

---

1. 命名约定

元素	风格	示例
命名空间	snake_case	vde::core
类/结构体	PascalCase	HalfedgeMesh
函数/方法	snake_case	compute_convex_hull()
变量	snake_case	vertex_count
成员变量	snake_case_	vertices_
常量	UPPER_SNAKE_CASE	MAX_ITERATIONS
枚举值	kPascalCase	kSuccess
宏前缀	VDE_	VDE_VERSION_MAJOR

---

2. 核心接口抽象

2.1 空间索引接口

namespace vde::spatial {

template <typename T>
class SpatialIndex {
public:
    virtual ~SpatialIndex() = default;
    virtual void build(const std::vector<T>& items) = 0;
    virtual void insert(const T& item) = 0;
    virtual bool remove(const T& item) = 0;
    virtual std::vector<T> query_range(const AABB3D& range) const = 0;
    virtual std::vector<T> query_knn(const Point3D& point, size_t k) const = 0;
    virtual std::vector<T> query_ray(const Ray3Dd& ray) const = 0;
    virtual void clear() = 0;
    virtual size_t size() const = 0;
};

}

2.2 曲线求值接口

namespace vde::curves {

template <typename T, size_t Dim>
class CurveBase {
public:
    virtual ~CurveBase() = default;
    virtual int degree() const = 0;
    virtual std::pair<double, double> domain() const = 0;
    virtual Point<T, Dim> evaluate(double t) const = 0;
    virtual Vector<T, Dim> derivative(double t, int order = 1) const = 0;
    virtual const std::vector<Point<T, Dim>>& control_points() const = 0;
};

}

2.3 网格数据结构接口

namespace vde::mesh {

class MeshBase {
public:
    virtual ~MeshBase() = default;
    virtual size_t num_vertices() const = 0;
    virtual size_t num_faces() const = 0;
    virtual const Point3D& vertex(size_t idx) const = 0;
    virtual std::vector<size_t> vertex_faces(size_t idx) const = 0;
    virtual Vector3D face_normal(size_t idx) const = 0;
    virtual Vector3D vertex_normal(size_t idx) const = 0;
    virtual bool is_boundary_vertex(size_t idx) const = 0;
    virtual void update_normals() = 0;
};

}

2.4 布尔运算接口

namespace vde::boolean {

enum class BooleanOp { Union, Intersection, Difference, SymDiff };

template <typename GeometryType>
class BooleanEngine {
public:
    virtual ~BooleanEngine() = default;
    virtual GeometryType execute(
        const GeometryType& a, const GeometryType& b, BooleanOp op) = 0;
    virtual void set_tolerance(double tol) = 0;
};

}

---

3. 稳定 C API（可选）

为跨语言绑定提供纯 C 接口：

// 创建与销毁上下文
vde_ctx_t vde_engine_create(void);
void vde_engine_destroy(vde_ctx_t ctx);

// 布尔运算
vde_mesh_t vde_boolean_union(vde_ctx_t ctx, vde_mesh_t a, vde_mesh_t b);

// 网格简化
vde_mesh_t vde_mesh_simplify(vde_ctx_t ctx, vde_mesh_t m, double ratio);

---

4. 错误处理约定

• 所有公开 API 返回值使用 Result<T> 类型（std::expected<T, ErrorCode> 的兼容实现）
• 错误码枚举定义于 vde/foundation/error_codes.h
• 内部实现可使用断言（assert），但公开 API 不抛异常
• using Result<T> = tl::expected<T, ErrorCode>;

错误码	说明
kSuccess	操作成功
kInvalidArgument	非法参数
kInvalidGeometry	非法几何（退化/非流形）
kDegenerateCase	退化情况
kNotImplemented	未实现
kNumericalError	数值计算错误