ssdfasd
008fb98dee
- SceneManager: remove singleton, use dependency injection via EditorContext - SelectionManager: already interface-based via ISelectionManager - Panel: now receives IEditorContext for accessing managers - HierarchyPanel: migrated to use IEditorContext instead of singletons - Add ISceneManager interface and SceneManagerImpl - EditorContextImpl: holds all editor subsystems Architecture now follows dependency injection pattern: Application -> EditorContext -> SceneManager/SelectionManager EditorLayer -> Panels (receive context via SetContext) All Manager singletons removed: EditorSceneManager::Get(), SelectionManager::Get()
336 lines
9.2 KiB
Markdown
336 lines
9.2 KiB
Markdown
# 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+ 支持
|