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

2026-03-22 01:28:21 +08:00
parent a172d75e36
commit 6e5ed41fbf
1 changed files with 138 additions and 59 deletions
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@

 ## 项目概述

-XCEngine 是一个正在开发中的游戏引擎，采用 RHI（Render Hardware Interface）抽象层设计，支持 DirectX 12 和 OpenGL 多种渲染 API。项目采用模块化设计，包含核心库和单元测试。
+XCEngine 是一个正在开发中的游戏引擎，采用 RHI（Render Hardware Interface）抽象层设计，支持 DirectX 12 和 OpenGL 多种渲染 API。项目采用模块化设计，包含核心库、示例程序和单元测试。

 ## 技术栈

@@ -19,6 +19,23 @@ XCEngine 是一个正在开发中的游戏引擎，采用 RHI（Render Hardware
 XCEngine/
 ├── engine/                         # 核心引擎库
 │   ├── include/XCEngine/
+│   │   ├── 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          # 字符串类
@@ -56,6 +73,7 @@ XCEngine/
 │   │   │   ├── Ray.h             # 射线
 │   │   │   ├── AABB.h            # 轴对齐包围盒
 │   │   │   ├── Bounds.h          # 包围体
+│   │   │   ├── OBB.h             # 方向包围盒
 │   │   │   ├── Frustum.h         # 视锥体
 │   │   │   └── Math.h            # 数学库统一头文件
 │   │   ├── Memory/              # 内存管理模块
@@ -73,7 +91,6 @@ XCEngine/
 │   │   │   ├── LambdaTask.h      # Lambda 任务
 │   │   │   ├── TaskGroup.h       # 任务组
 │   │   │   ├── TaskSystem.h      # 任务系统
-│   │   │   ├── TaskSystemConfig.h # 任务系统配置
 │   │   │   └── Threading.h       # 线程模块统一头文件
 │   │   ├── Resources/           # 资源管理模块
 │   │   │   ├── ResourceTypes.h   # 资源类型定义
@@ -102,6 +119,9 @@ XCEngine/
 │   │   │   ├── AudioClip.h       # 音频资源
 │   │   │   ├── AudioLoader.h     # 音频加载器
 │   │   │   └── Resources.h       # 资源模块统一头文件
+│   │   ├── Scene/               # 场景管理模块
+│   │   │   ├── Scene.h           # 场景类
+│   │   │   └── SceneManager.h    # 场景管理器
 │   │   └── RHI/                  # 渲染硬件接口抽象层
 │   │       ├── RHITypes.h        # RHI 类型定义
 │   │       ├── RHIEnums.h        # RHI 枚举
@@ -158,35 +178,66 @@ 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/                        # 单元测试
 │   ├── 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/              # 基础渲染示例
+│   ├── D3D12/                   # DirectX 12 渲染示例
+│   ├── OpenGL/                  # OpenGL 渲染示例
+│   ├── Music fluctuations/       # 音频可视化示例
 │   ├── VolumeRenderer/          # 体积渲染器（NanoVDB）
-│   └── ui/                      # 编辑器 UI
+│   └── ui/                     # 编辑器 UI 示例
 │
-├── docs/                         # 设计文档
+├── ui_editor/                   # 编辑器 UI 应用程序
+│   ├── src/                     # 编辑器源代码
+│   ├── bin/                     # 资源文件
+│   └── build/                   # 构建目录
+│
+├── docs/                        # 文档
 │   ├── api/                    # API 文档
+│   │   ├── 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/                   # 开发计划与架构设计
 │
+├── 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/` 目录。

 ## 许可证