XCEngine/.trae/documents/XCEngine项目熟悉计划.md

# XCEngine 项目熟悉计划

## 项目概述

XCEngine 是一个正在开发中的模块化 C++ 游戏引擎，采用 RHI（Render Hardware Interface）抽象层设计，支持 DirectX 12 和 OpenGL 4.6+ 多种渲染 API。

### 技术栈
- **语言**: C++17
- **渲染 API**: DirectX 12, OpenGL 4.6+
- **构建系统**: CMake 3.15+
- **测试框架**: Google Test
- **UI**: ImGui（用于编辑器）

---

## 项目结构

```
XCEngine/
├── engine/                 # 核心引擎库（静态库）
│   ├── include/XCEngine/   # 头文件
│   │   ├── Audio/          # 音频系统
│   │   ├── Components/     # 组件系统
│   │   ├── Core/           # 核心基础模块
│   │   ├── Debug/          # 调试与日志
│   │   ├── Input/          # 输入模块
│   │   ├── Memory/         # 内存管理
│   │   ├── Platform/       # 平台抽象层
│   │   ├── RHI/            # 渲染硬件接口
│   │   ├── Resources/      # 资源管理
│   │   ├── Scene/          # 场景管理
│   │   └── Threading/      # 线程系统
│   ├── src/                # 实现文件
│   └── third_party/        # 第三方库
│
├── editor/                 # 编辑器 UI 应用程序
│   └── src/                # 编辑器源代码
│
├── tests/                  # 单元测试
│   ├── math/               # 数学库测试
│   ├── containers/         # 容器测试
│   ├── memory/             # 内存管理测试
│   ├── threading/          # 线程模块测试
│   ├── debug/              # 调试模块测试
│   ├── core/               # 核心模块测试
│   ├── Scene/              # 场景测试
│   ├── Resources/          # 资源管理测试
│   ├── Input/              # 输入模块测试
│   └── RHI/                # RHI 抽象层测试
│
├── mvs/                    # 示例程序
│   ├── D3D12/              # DirectX 12 渲染示例
│   ├── OpenGL/             # OpenGL 渲染示例
│   ├── VolumeRenderer/     # 体积渲染器
│   ├── RenderDoc/          # RenderDoc 集成示例
│   └── ui/                 # 编辑器 UI 示例
│
└── docs/                   # 文档
    ├── api/                # API 文档
    └── plan/               # 开发计划与架构设计
```

---

## 核心模块详解

### 1. Core（核心基础）

位置: `engine/include/XCEngine/Core/`

| 子模块 | 说明 |
|--------|------|
| Types.h | 基础类型别名（int8, uint32 等） |
| RefCounted.h | 引用计数基类 |
| SmartPtr.h | 智能指针（Ref, UniqueRef） |
| Event.h | 事件系统，支持订阅/发布模式 |
| FileWriter.h | 文件写入工具 |
| Layer.h/LayerStack.h | 层级与层级栈管理 |

**Core/Math 数学库**:
- Vector2/3/4 - 向量运算
- Matrix3/4 - 矩阵运算
- Quaternion - 四元数
- Transform - 变换
- Color - 颜色
- Rect - 矩形
- Sphere/Box/Plane/Ray - 几何体
- AABB/Bounds/Frustum - 包围体

**Core/Containers 容器**:
- Array.h - 动态数组
- String.h - 字符串类
- HashMap.h - 哈希表

**Core/Asset 资源系统核心**:
- IResource.h - 资源接口基类
- ResourceTypes.h - 资源类型定义
- ResourceHandle.h - 资源句柄
- ResourceManager.h - 全局资源管理器
- ResourceCache.h - 资源缓存
- AsyncLoader.h - 异步资源加载器

**Core/IO 资源 IO 系统**:
- IResourceLoader.h - 资源加载器接口
- ResourceFileSystem.h - 资源文件系统
- FileArchive.h - 文件归档

### 2. RHI（渲染硬件接口）

位置: `engine/include/XCEngine/RHI/`

这是引擎的核心抽象层，借鉴 Unity SRP 架构设计。

**设计原则**:
- 求同存异：提取各 API 共同特性
- 分层抽象：核心抽象层 → 后端实现层 → 平台适配层
- 特性降级：后端不支持的特性优雅降级

**抽象接口**:
| 接口 | 说明 |
|------|------|
| RHIDevice | 渲染设备抽象 |
| RHICommandQueue | 命令队列抽象 |
| RHICommandList | 命令列表抽象 |
| RHISwapChain | 交换链抽象 |
| RHIPipelineState | 渲染管线状态抽象 |
| RHIBuffer/RHITexture | 资源抽象 |
| RHIShader | 着色器抽象 |
| RHISampler | 采样器抽象 |
| RHIFence | 同步栅栏抽象 |
| RHIDescriptorPool | 描述符池抽象 |
| RHIRenderPass | 渲染通道抽象 |
| RHIFramebuffer | 帧缓冲抽象 |

**后端实现**:
- `RHI/D3D12/` - DirectX 12 后端
- `RHI/OpenGL/` - OpenGL 4.6+ 后端

### 3. Components（组件系统）

位置: `engine/include/XCEngine/Components/`

采用类似 Unity 的组件架构：

| 组件 | 说明 |
|------|------|
| Component.h | 组件基类，提供生命周期管理 |
| GameObject.h | 游戏对象，支持层级结构 |
| TransformComponent.h | 变换组件 |
| AudioSourceComponent.h | 音频源组件 |
| AudioListenerComponent.h | 音频监听器组件 |

### 4. Scene（场景管理）

位置: `engine/include/XCEngine/Scene/`

- **Scene.h** - 场景类，管理场景内的所有游戏对象
- **SceneManager.h** - 场景管理器，处理场景切换

### 5. Audio（音频系统）

位置: `engine/include/XCEngine/Audio/`

| 模块 | 说明 |
|------|------|
| AudioSystem.h | 音频系统主类 |
| AudioMixer.h | 音频混音器 |
| HRTF.h | 头部相关传输函数，空间音频 |
| FFTFilter.h | 快速傅里叶变换滤波器 |
| Reverbation.h | 混响效果 |
| Equalizer.h | 音频均衡器 |
| IAudioBackend.h | 音频后端接口 |
| WindowsAudioBackend.h | Windows WASAPI 后端 |

### 6. Memory（内存管理）

位置: `engine/include/XCEngine/Memory/`

| 模块 | 说明 |
|------|------|
| Allocator.h | 内存分配器接口 |
| LinearAllocator.h | 线性分配器，适合帧分配 |
| PoolAllocator.h | 内存池分配器，适合固定大小对象 |
| ProxyAllocator.h | 代理分配器，跟踪内存使用统计 |
| MemoryManager.h | 全局内存管理器 |

### 7. Threading（线程系统）

位置: `engine/include/XCEngine/Threading/`

| 模块 | 说明 |
|------|------|
| Thread.h | 线程封装类 |
| Mutex.h | 互斥锁 |
| SpinLock.h | 自旋锁 |
| ReadWriteLock.h | 读写锁 |
| TaskSystem.h | 多线程任务系统 |
| Task.h/TaskGroup.h | 任务和任务组管理 |

### 8. Debug（调试与日志）

位置: `engine/include/XCEngine/Debug/`

| 模块 | 说明 |
|------|------|
| Logger.h | 分级日志系统 |
| ConsoleLogSink.h | 控制台日志输出 |
| FileLogSink.h | 文件日志输出 |
| Profiler.h | 性能分析工具 |
| RenderDocCapture.h | RenderDoc 帧捕获集成 |

### 9. Resources（资源管理）

位置: `engine/include/XCEngine/Resources/`

按类型分目录管理：
- **Texture/** - 纹理资源
- **Mesh/** - 网格资源
- **Shader/** - 着色器资源
- **Material/** - 材质资源
- **AudioClip/** - 音频资源

### 10. Platform（平台抽象层）

位置: `engine/include/XCEngine/Platform/`

跨平台抽象接口：
- IPlatform - 平台接口
- IWindow - 窗口接口
- IFileSystem - 文件系统接口
- IClock - 时钟接口
- Windows/ - Windows 平台实现

### 11. Input（输入模块）

位置: `engine/include/XCEngine/Input/`

- InputManager - 输入管理器
- InputModule - 输入模块基类
- InputEvent - 输入事件定义
- InputAxis - 输入轴配置

---

## 渲染架构

### 渲染流程

```
Scene → CullingSystem → RenderQueue → Renderer → GPU
         ↓                               ↓
    CullingResults              CommandList
```

### 关键概念（借鉴 Unity SRP）

1. **CullingResults** - 剔除结果
2. **RenderPipeline** - 渲染管线
3. **RenderQueue** - 渲染队列
4. **ScriptableRenderContext** - 渲染上下文
5. **LightManager** - 光照管理
6. **ShadowAtlas** - 阴影图集

---

## 构建与测试

### 构建项目

```bash
mkdir build && cd build
cmake .. -A x64
cmake --build . --config Debug
```

### 运行测试

```bash
cd build/tests
ctest -C Debug --output-on-failure
```

---

## 学习路径建议

### 第一阶段：核心基础
1. 阅读 `README.md` 了解项目概述
2. 学习 Core 模块（Types, Event, SmartPtr）
3. 学习 Math 数学库
4. 学习 Containers 容器

### 第二阶段：系统模块
1. 学习 Memory 内存管理
2. 学习 Threading 线程系统
3. 学习 Debug 日志系统
4. 学习 Platform 平台抽象

### 第三阶段：渲染系统
1. 学习 RHI 抽象层设计
2. 学习 D3D12 后端实现
3. 学习 OpenGL 后端实现
4. 学习渲染管线架构

### 第四阶段：高级功能
1. 学习 Scene 场景管理
2. 学习 Components 组件系统
3. 学习 Resources 资源管理
4. 学习 Audio 音频系统

### 第五阶段：实践
1. 运行 mvs 中的示例程序
2. 阅读测试用例理解 API 用法
3. 尝试修改或扩展现有功能

---

## 关键文件索引

| 文件 | 说明 |
|------|------|
| README.md | 项目说明文档 |
| CMakeLists.txt | 根构建配置 |
| engine/CMakeLists.txt | 引擎库构建配置 |
| docs/plan/XCEngine渲染引擎架构设计.md | 渲染架构详细设计 |
| docs/api/main.md | API 文档入口 |

---

## 注意事项

1. 项目目前仅支持 Windows 平台
2. 需要 Visual Studio 2019 或更高版本
3. D3D12 后端需要 Windows 10/11
4. OpenGL 后端需要 OpenGL 4.6+ 支持