From 6e5ed41fbf0634f175dc3a3d1c2b068b65462e61 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Sun, 22 Mar 2026 01:28:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=A8=E9=9D=A2=E6=9B=B4=E6=96=B0=20?= =?UTF-8?q?README.md=20=E9=A1=B9=E7=9B=AE=E7=BB=93=E6=9E=84=E6=8F=8F?= =?UTF-8?q?=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 197 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 138 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 4e3226d6..77149342 100644 --- 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,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/` 目录。 ## 许可证