xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 全面更新 README.md 项目结构描述

Browse Source
This commit is contained in:
ssdfasd
2026-03-22 01:28:21 +08:00
parent a172d75e36
commit 6e5ed41fbf
1 changed files with 138 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
README.md
View File

@@ -4,7 +4,7 @@
## 项目概述
XCEngine 是一个正在开发中的游戏引擎，采用 RHI（Render Hardware Interface）抽象层设计，支持 DirectX 12 和 OpenGL 多种渲染 API。项目采用模块化设计，包含核心库和单元测试。
XCEngine 是一个正在开发中的游戏引擎，采用 RHI（Render Hardware Interface）抽象层设计，支持 DirectX 12 和 OpenGL 多种渲染 API。项目采用模块化设计，包含核心库、示例程序和单元测试。
## 技术栈
@@ -19,18 +19,35 @@ XCEngine 是一个正在开发中的游戏引擎，采用 RHI（Render Hardware
XCEngine/
├── engine/ # 核心引擎库
│ ├── include/XCEngine/
│ │ ├── Containers/ # 容器模块
│ │ ├── Audio/ # 音频系统
│ │ │ ├── AudioSystem.h # 音频系统主类
│ │ │ ├── AudioTypes.h # 音频类型定义
│ │ │ ├── AudioConfig.h # 音频配置
│ │ │ ├── AudioMixer.h # 音频混音器
│ │ │ ├── AudioSourceComponent.h # 音频源组件
│ │ │ ├── AudioListenerComponent.h # 音频监听器组件
│ │ │ ├── HRTF.h # HRTF 空间音频
│ │ │ ├── FFTFilter.h # FFT 滤波器
│ │ │ ├── Reverbation.h # 混响效果
│ │ │ ├── Equalizer.h # 均衡器
│ │ │ ├── WASAPI/ # WASAPI 后端实现
│ │ │ └── IAudioBackend.h # 音频后端接口
│ │ ├── Components/ # 游戏组件系统
│ │ │ ├── Component.h # 组件基类
│ │ │ ├── GameObject.h # 游戏对象
│ │ │ └── TransformComponent.h # 变换组件
│ │ ├── Containers/ # 容器模块
│ │ │ ├── Array.h # 动态数组
│ │ │ ├── String.h # 字符串类
│ │ │ ├── HashMap.h # 哈希表
│ │ │ └── Containers.h # 模块统一头文件
│ │ ├── Core/ # 核心基础模块
│ │ ├── Core/ # 核心基础模块
│ │ │ ├── Types.h # 基础类型别名
│ │ │ ├── RefCounted.h # 引用计数基类
│ │ │ ├── SmartPtr.h # 智能指针
│ │ │ ├── Event.h # 事件系统
│ │ │ └── FileWriter.h # 文件写入
│ │ ├── Debug/ # 调试与日志模块
│ │ ├── Debug/ # 调试与日志模块
│ │ │ ├── Logger.h # 日志系统
│ │ │ ├── LogLevel.h # 日志级别
│ │ │ ├── LogCategory.h # 日志分类
@@ -56,15 +73,16 @@ XCEngine/
│ │ │ ├── Ray.h # 射线
│ │ │ ├── AABB.h # 轴对齐包围盒
│ │ │ ├── Bounds.h # 包围体
│ │ │ ├── OBB.h # 方向包围盒
│ │ │ ├── Frustum.h # 视锥体
│ │ │ └── Math.h # 数学库统一头文件
│ │ ├── Memory/ # 内存管理模块
│ │ ├── Memory/ # 内存管理模块
│ │ │ ├── Allocator.h # 分配器接口
│ │ │ ├── LinearAllocator.h # 线性分配器
│ │ │ ├── PoolAllocator.h # 内存池分配器
│ │ │ ├── ProxyAllocator.h # 代理分配器
│ │ │ └── MemoryManager.h # 全局内存管理器
│ │ ├── Threading/ # 线程模块
│ │ ├── Threading/ # 线程模块
│ │ │ ├── Thread.h # 线程类
│ │ │ ├── Mutex.h # 互斥锁
│ │ │ ├── SpinLock.h # 自旋锁
@@ -73,9 +91,8 @@ XCEngine/
│ │ │ ├── LambdaTask.h # Lambda 任务
│ │ │ ├── TaskGroup.h # 任务组
│ │ │ ├── TaskSystem.h # 任务系统
│ │ │ ├── TaskSystemConfig.h # 任务系统配置
│ │ │ └── Threading.h # 线程模块统一头文件
│ │ ├── Resources/ # 资源管理模块
│ │ ├── Resources/ # 资源管理模块
│ │ │ ├── ResourceTypes.h # 资源类型定义
│ │ │ ├── IResource.h # 资源接口
│ │ │ ├── ResourceHandle.h # 资源句柄
@@ -92,34 +109,37 @@ XCEngine/
│ │ │ ├── Texture.h # 纹理资源
│ │ │ ├── TextureLoader.h # 纹理加载器
│ │ │ ├── TextureImportSettings.h # 纹理导入设置
│ │ │ ├── Mesh.h # 网格资源
│ │ │ ├── MeshLoader.h # 网格加载器
│ │ │ ├── Mesh.h # 网格资源
│ │ │ ├── MeshLoader.h # 网格加载器
│ │ │ ├── MeshImportSettings.h # 网格导入设置
│ │ │ ├── Shader.h # 着色器资源
│ │ │ ├── ShaderLoader.h # 着色器加载器
│ │ │ ├── Material.h # 材质资源
│ │ │ ├── MaterialLoader.h # 材质加载器
│ │ │ ├── AudioClip.h # 音频资源
│ │ │ ├── AudioLoader.h # 音频加载器
│ │ │ └── Resources.h # 资源模块统一头文件
│ │ └── RHI/ # 渲染硬件接口抽象层
│ │ │ ├── Shader.h # 着色器资源
│ │ │ ├── ShaderLoader.h # 着色器加载器
│ │ │ ├── Material.h # 材质资源
│ │ │ ├── MaterialLoader.h # 材质加载器
│ │ │ ├── AudioClip.h # 音频资源
│ │ │ ├── AudioLoader.h # 音频加载器
│ │ │ └── Resources.h # 资源模块统一头文件
│ │ ├── Scene/ # 场景管理模块
│ │ │ ├── Scene.h # 场景类
│ │ │ └── SceneManager.h # 场景管理器
│ │ └── RHI/ # 渲染硬件接口抽象层
│ │ ├── RHITypes.h # RHI 类型定义
│ │ ├── RHIEnums.h # RHI 枚举
│ │ ├── RHICapabilities.h # 硬件能力查询
│ │ ├── RHIFactory.h # 设备工厂
│ │ ├── RHIDevice.h # 渲染设备抽象
│ │ ├── RHICommandQueue.h # 命令队列抽象
│ │ ├── RHICommandList.h # 命令列表抽象
│ │ ├── RHIDevice.h # 渲染设备抽象
│ │ ├── RHICommandQueue.h # 命令队列抽象
│ │ ├── RHICommandList.h # 命令列表抽象
│ │ ├── RHIBuffer.h # 缓冲区抽象
│ │ ├── RHITexture.h # 纹理抽象
│ │ ├── RHIShader.h # 着色器抽象
│ │ ├── RHISampler.h # 采样器抽象
│ │ ├── RHIFence.h # 同步栅栏抽象
│ │ ├── RHISwapChain.h # 交换链抽象
│ │ ├── RHITexture.h # 纹理抽象
│ │ ├── RHIShader.h # 着色器抽象
│ │ ├── RHISampler.h # 采样器抽象
│ │ ├── RHIFence.h # 同步栅栏抽象
│ │ ├── RHISwapChain.h # 交换链抽象
│ │ ├── RHIPipelineState.h # 管线状态抽象
│ │ ├── RHIPipelineLayout.h # 管线布局抽象
│ │ ├── RHIDescriptorPool.h # 描述符池抽象
│ │ ├── RHIDescriptor.h # 描述符抽象
│ │ ├── RHIDescriptor.h # 描述符抽象
│ │ ├── OpenGL/ # OpenGL 后端实现
│ │ │ ├── OpenGLDevice.h
│ │ │ ├── OpenGLCommandQueue.h
@@ -134,7 +154,7 @@ XCEngine/
│ │ │ ├── OpenGLVertexArray.h
│ │ │ ├── OpenGLRenderTargetView.h
│ │ │ └── OpenGLDepthStencilView.h
│ │ └── D3D12/ # DirectX 12 后端实现
│ │ └── D3D12/ # DirectX 12 后端实现
│ │ ├── D3D12Device.h
│ │ ├── D3D12CommandQueue.h
│ │ ├── D3D12CommandAllocator.h
@@ -158,36 +178,67 @@ XCEngine/
│ │ ├── D3D12Types.h
│ │ ├── D3D12Enum.h
│ │ └── D3D12Common.h
│ └── src/ # 实现文件
│ ├── Containers/
│ ├── Core/
│ ├── Debug/
│ ├── Math/
│ ├── Memory/
│ ├── Threading/
│ ├── Resources/
│ └── RHI/
│ ├── src/ # 实现文件
│ │ ├── Audio/
│ │ ├── Containers/
│ │ ├── Core/
│ │ ├── Debug/
│ │ ├── Math/
│ │ ├── Memory/
│ │ ├── Threading/
│ │ ├── Resources/
│ │ ├── Scene/
│ │ └── RHI/
│ └── third_party/ # 第三方库
│ ├── kissfft/ # FFT 库
│ └── stb/ # 图像处理库
│
├── tests/ # 单元测试
├── tests/ # 单元测试
│ ├── containers/ # 容器测试
│ ├── memory/ # 内存管理测试
│ ├── threading/ # 线程模块测试
│ ├── core/ # 核心模块测试
│ ├── debug/ # 调试模块测试
│ ├── math/ # 数学库测试
│ ├── Components/ # 组件测试
│ ├── Scene/ # 场景测试
│ ├── Resources/ # 资源管理测试
│ └── RHI/ # RHI 抽象层测试
│ ├── OpenGL/ # OpenGL 后端测试
│ │ ├── unit/ # 单元测试 (14)
│ │ └── integration/ # 集成测试 (5)
│ └── D3D12/ # D3D12 后端测试
│ ├── unit/ # 单元测试 (15)
│ └── integration/ # 集成测试 (8)
│
├── mvs/ # 示例程序
│ ├── HelloEarth/ # 基础渲染示例
│ ├── VolumeRenderer/ # 体积渲染器（NanoVDB）
│ └── ui/ # 编辑器 UI
│ ├── D3D12/ # DirectX 12 渲染示例
│ ├── OpenGL/ # OpenGL 渲染示例
│ ├── Music fluctuations/ # 音频可视化示例
│ ├── VolumeRenderer/ # 体积渲染器（NanoVDB）
│ └── ui/ # 编辑器 UI 示例
│
├── docs/ # 设计文档
├── ui_editor/ # 编辑器 UI 应用程序
│ ├── src/ # 编辑器源代码
│ ├── bin/ # 资源文件
│ └── build/ # 构建目录
│
├── docs/ # 文档
│ ├── api/ # API 文档
│ └── plan/ # 开发计划与架构设计
│ │ ├── rhi/ # RHI API 文档
│ │ ├── math/ # Math API 文档
│ │ ├── containers/ # Containers API 文档
│ │ ├── threading/ # Threading API 文档
│ │ ├── memory/ # Memory API 文档
│ │ ├── core/ # Core API 文档
│ │ ├── debug/ # Debug API 文档
│ │ ├── resources/ # Resources API 文档
│ │ └── main.md # API 文档总索引
│ └── plan/ # 开发计划与架构设计
│
└── build/ # 构建目录
├── scripts/ # 构建和测试脚本
│
└── build/ # 构建目录
```
## 快速开始
@@ -228,6 +279,23 @@ build/tests/threading/Debug/xcengine_threading_tests.exe
## 核心模块说明
### Audio（音频系统）
- **AudioSystem**: 音频系统主类，管理所有音频设备
- **HRTF**: 头部相关传输函数，支持空间音频定位
- **FFTFilter**: 快速傅里叶变换滤波器
- **Reverbation**: 混响效果
- **Equalizer**: 音频均衡器
- **WASAPI**: Windows 音频会话 API 后端实现
- **AudioSourceComponent**: 音频源组件（用于游戏对象）
- **AudioListenerComponent**: 音频监听器组件（用于游戏对象）
### Components（游戏组件系统）
- **Component**: 组件基类，提供生命周期管理
- **GameObject**: 游戏对象，支持层级结构
- **TransformComponent**: 变换组件，管理位置、旋转、缩放
### Containers（容器）
- **String**: 动态字符串类，支持常用字符串操作
@@ -276,7 +344,7 @@ build/tests/threading/Debug/xcengine_threading_tests.exe
- **Rect**: 矩形
- **Sphere/Box/Plane**: 基本几何体
- **Ray**: 射线
- **AABB/Bounds**: 包围体
- **AABB/Bounds/OBB**: 包围体
- **Frustum**: 视锥体
### Resources（资源管理）
@@ -290,6 +358,11 @@ build/tests/threading/Debug/xcengine_threading_tests.exe
- **IResourceLoader**: 资源加载器接口
- **Texture/Mesh/Shader/Material/AudioClip**: 各类资源类型
### Scene（场景管理）
- **Scene**: 场景类，管理场景内的所有游戏对象
- **SceneManager**: 场景管理器，处理场景切换
### RHI（渲染硬件接口）
XCEngine 采用 RHI（Render Hardware Interface）抽象层设计，支持多渲染后端。
@@ -318,11 +391,6 @@ XCEngine 采用 RHI（Render Hardware Interface）抽象层设计，支持多渲
- **OpenGL 后端**: OpenGL 4.6+ 支持
- **D3D12 后端**: DirectX 12 支持
#### 测试覆盖
- OpenGL 后端: 41 个测试用例通过
- D3D12 后端: 编译通过
## 测试覆盖
| 模块 | 测试用例数 |
@@ -330,24 +398,26 @@ XCEngine 采用 RHI（Render Hardware Interface）抽象层设计，支持多渲
| Containers | 51+ |
| Memory | 19 |
| Threading | 13 |
| Math | 通过 |
| RHI (OpenGL) | 41 |
| RHI (D3D12) | 编译通过 |
| Math | 5+ |
| Components | 2+ |
| Scene | 2+ |
| Resources | 4+ |
| RHI (OpenGL) | 41 (unit 14 + integration 5) |
| RHI (D3D12) | 23 (unit 15 + integration 8) |
## mvs 示例程序
mvs（Multiple Version Samples）展示游戏引擎的各类功能。所有示例均基于 RHI 抽象层开发，可无缝切换 DirectX 12 或 OpenGL 后端。
### HelloEarth（开发中）
### D3D12 / OpenGL
基础的跨平台渲染示例，展示如何：
跨平台渲染示例，展示如何：
- 初始化 RHI 渲染环境（支持 D3D12/OpenGL）
- 加载和渲染静态网格
- 使用几何着色器
- 纹理映射
- 常量缓冲区更新
### VolumeRenderer（开发中）
### VolumeRenderer
XCEngine 的体积渲染模块，基于 NanoVDB 实现云、烟雾等体积数据的实时渲染：
- NanoVDB 格式体积数据加载
@@ -356,7 +426,14 @@ XCEngine 的体积渲染模块，基于 NanoVDB 实现云、烟雾等体积数
- 体积阴影（Volumetric Shadow）
- 动态光照参数调节
### UI Editor（开发中）
### Music fluctuations
音频可视化示例，基于 FFT 实时分析音频频谱：
- 音频播放与 FFT 分析
- 频谱可视化渲染
- 音频与视觉效果同步
### UI Editor
Unity 风格的编辑器 UI，基于 ImGui 实现：
- 场景层级面板
@@ -367,7 +444,9 @@ Unity 风格的编辑器 UI，基于 ImGui 实现：
## 文档
更多详细设计文档请参考 `docs/` 目录。
API 文档位于 `docs/api/` 目录，包含各模块的完整 API 参考。
详细设计文档请参考 `docs/plan/` 目录。
## 许可证