v0.1.0: 初始工程骨架 — 7模块 40头文件 32源文件 17文档 Apache-2.0

2026-07-23 05:27:51 +00:00
commit 02d0520aa5
133 changed files with 5350 additions and 0 deletions
@@ -0,0 +1,115 @@
+# 编码规范
+
+## 目录
+
+1. [C++ 标准](#1-c-标准)
+2. [命名规范](#2-命名规范)
+3. [头文件规范](#3-头文件规范)
+4. [代码风格](#4-代码风格)
+5. [注释规范](#5-注释规范)
+6. [内存管理](#6-内存管理)
+7. [错误处理](#7-错误处理)
+8. [性能规范](#8-性能规范)
+
+---
+
+## 1. C++ 标准
+
+- **目标标准**：C++17
+- **编译器**：GCC 9+, Clang 12+, MSVC 2019+
+- **允许的 C++17 特性**：
+  - structured bindings、`if constexpr`、fold expressions
+  - `std::string_view`、`std::optional`
+  - `[[nodiscard]]`、`[[maybe_unused]]`
+  - CTAD（类模板参数推导）
+
+---
+
+## 2. 命名规范
+
+| 元素 | 风格 | 示例 |
+|------|------|------|
+| 命名空间 | snake_case | `vde::core` |
+| 类/结构体 | PascalCase | `HalfedgeMesh` |
+| 函数/方法 | snake_case | `compute_convex_hull()` |
+| 成员变量 | snake_case_ | `vertices_` |
+| 常量 | UPPER_SNAKE_CASE | `MAX_ITERATIONS` |
+| 枚举值 | kPascalCase | `kSuccess` |
+| 宏 | VDE_UPPER_SNAKE | `VDE_VERSION_MAJOR` |
+
+---
+
+## 3. 头文件规范
+
+```cpp
+#pragma once  // 优先使用
+
+// 包含顺序（每组间空行分隔）：
+// 1. 对应的 .h 文件（.cpp 中）
+// 2. C++ 标准库
+// 3. 第三方库（Eigen）
+// 4. 本项目头文件
+
+#include "vde/core/point.h"
+
+#include <cmath>
+#include <vector>
+
+#include <Eigen/Core>
+
+#include "vde/core/aabb.h"
+```
+
+---
+
+## 4. 代码风格
+
+- **缩进**：4 空格，不使用 Tab
+- **行宽**：上限 100 字符
+- **格式化**：统一使用 `.clang-format`（Google 风格变体）
+- **短函数**：单行内联
+- **大括号**：函数/类/结构体后换行，控制流不换行
+
+---
+
+## 5. 注释规范
+
+- **公开 API**：使用 Doxygen 风格（`///`）
+- **内部实现**：使用 `//` 行注释
+- **复杂算法**：必须注释算法来源（论文引用或公式）
+- **禁止**：注释掉的代码（使用版本控制回溯）
+
+---
+
+## 6. 内存管理
+
+- **禁止**裸 `new`/`delete`
+- 使用 `std::make_unique` / `std::make_shared`
+- 大块连续内存使用 `std::vector`
+- 小型对象优先栈分配
+- 性能关键路径使用自定义 `MemoryPool`
+
+---
+
+## 7. 错误处理
+
+```cpp
+// 公开 API 返回值类型
+template <typename T>
+using Result = tl::expected<T, ErrorCode>;
+
+// 内部断言
+assert(condition && "message");
+```
+
+- 公开 API 不抛异常
+- 内部可抛异常，但必须提供异常安全保证
+
+---
+
+## 8. 性能规范
+
+- 函数参数：基本类型传值，大对象传 `const&`，sink 参数传 `&&`
+- 循环中避免重复计算：hoist 不变量
+- 容器预分配：`reserve()` 已知大小
+- 避免隐藏的临时对象拷贝
@@ -0,0 +1,125 @@
+# 工程目录结构
+
+## 目录
+
+1. [完整目录树](#1-完整目录树)
+2. [CMakeLists.txt 骨架](#2-cmakeliststxt-骨架)
+
+---
+
+## 1. 完整目录树
+
+```
+ViewDesignEngine/
+├── CMakeLists.txt                  # 根 CMake 配置
+├── README.md                       # 项目说明
+├── .clang-format                   # 代码格式化配置
+├── .gitignore
+│
+├── cmake/                          # CMake 模块
+│   └── CompilerSettings.cmake      # 编译器警告/优化配置
+│
+├── include/                        # 公开头文件
+│   └── vde/                        # 命名空间 vde::
+│       ├── foundation/             # 基础设施层
+│       │   ├── math_types.h
+│       │   ├── tolerance.h
+│       │   ├── error_codes.h
+│       │   ├── exact_predicates.h
+│       │   ├── memory_pool.h
+│       │   ├── io_obj.h
+│       │   └── io_stl.h
+│       ├── core/                   # 几何核心层
+│       │   ├── point.h
+│       │   ├── line.h
+│       │   ├── plane.h
+│       │   ├── triangle.h
+│       │   ├── polygon.h
+│       │   ├── aabb.h
+│       │   ├── transform.h
+│       │   ├── distance.h
+│       │   └── convex_hull.h
+│       ├── curves/                 # 曲线曲面层
+│       │   ├── bezier_curve.h
+│       │   ├── bspline_curve.h
+│       │   ├── nurbs_curve.h
+│       │   ├── bezier_surface.h
+│       │   ├── bspline_surface.h
+│       │   └── tessellation.h
+│       ├── mesh/                   # 网格处理层
+│       │   ├── halfedge_mesh.h
+│       │   ├── delaunay_2d.h
+│       │   ├── mesh_simplify.h
+│       │   ├── mesh_smooth.h
+│       │   ├── mesh_boolean.h
+│       │   ├── mesh_quality.h
+│       │   └── mesh_repair.h
+│       ├── spatial/                # 空间索引层
+│       │   ├── spatial_index.h
+│       │   ├── bvh.h
+│       │   ├── octree.h
+│       │   ├── kd_tree.h
+│       │   └── r_tree.h
+│       ├── boolean/                # 布尔运算层
+│       │   ├── boolean_2d.h
+│       │   └── boolean_mesh.h
+│       └── collision/              # 碰撞检测层
+│           ├── gjk.h
+│           ├── sat.h
+│           ├── ray_intersect.h
+│           └── tri_intersect.h
+│
+├── src/                            # 实现文件（与 include 镜像）
+│
+├── tests/                          # 单元测试
+│   ├── core/                       # 测试几何核心
+│   ├── curves/                     # 测试曲线曲面
+│   ├── mesh/                       # 测试网格处理
+│   ├── spatial/                    # 测试空间索引
+│   ├── collision/                  # 测试碰撞检测
+│   └── boolean/                    # 测试布尔运算
+│
+├── examples/                       # 示例程序
+│   ├── 01_hello_triangle/
+│   ├── 02_bezier/
+│   ├── 03_mesh/
+│   ├── 04_delaunay/
+│   ├── 05_boolean/
+│   └── 06_collision/
+│
+├── benchmarks/                     # 性能测试
+├── data/                           # 测试数据
+│   ├── meshes/
+│   └── curves/
+└── docs/                           # 工程文档
+```
+
+---
+
+## 2. CMakeLists.txt 骨架
+
+```cmake
+cmake_minimum_required(VERSION 3.16)
+project(ViewDesignEngine VERSION 0.1.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# 选项
+option(BUILD_TESTS "构建单元测试" ON)
+option(BUILD_EXAMPLES "构建示例程序" ON)
+
+# 依赖（自动 FetchContent）
+find_package(Eigen3 3.3 QUIET)
+# 若未找到，使用 FetchContent 下载
+
+# 子目录
+add_subdirectory(src)
+if(BUILD_TESTS)
+    enable_testing()
+    add_subdirectory(tests)
+endif()
+if(BUILD_EXAMPLES)
+    add_subdirectory(examples)
+endif()
+```