# XCEngine 基于 DirectX 12 的游戏引擎项目，支持体积渲染、跨平台渲染后端和核心模块单元测试。 ## 项目概述 XCEngine 是一个正在开发中的游戏引擎，采用 RHI（Render Hardware Interface）抽象层设计，支持 DirectX 12 和 OpenGL 多种渲染 API。项目采用模块化设计，包含核心库、示例程序和单元测试。 ## 技术栈 - **渲染 API**: DirectX 12, OpenGL 4.6+ - **语言**: C++17 - **构建系统**: CMake - **测试框架**: Google Test ## 项目结构 ``` 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 # 字符串类 │ │ │ ├── HashMap.h # 哈希表 │ │ │ └── Containers.h # 模块统一头文件 │ │ ├── Core/ # 核心基础模块 │ │ │ ├── Types.h # 基础类型别名 │ │ │ ├── RefCounted.h # 引用计数基类 │ │ │ ├── SmartPtr.h # 智能指针 │ │ │ ├── Event.h # 事件系统 │ │ │ └── FileWriter.h # 文件写入 │ │ ├── Debug/ # 调试与日志模块 │ │ │ ├── Logger.h # 日志系统 │ │ │ ├── LogLevel.h # 日志级别 │ │ │ ├── LogCategory.h # 日志分类 │ │ │ ├── LogEntry.h # 日志条目 │ │ │ ├── ConsoleLogSink.h # 控制台输出 │ │ │ ├── FileLogSink.h # 文件输出 │ │ │ ├── ILogSink.h # 日志槽接口 │ │ │ ├── Debug.h # 调试宏 │ │ │ └── Profiler.h # 性能分析 │ │ ├── Math/ # 数学库 │ │ │ ├── Vector2.h # 二维向量 │ │ │ ├── Vector3.h # 三维向量 │ │ │ ├── Vector4.h # 四维向量 │ │ │ ├── Matrix3.h # 3x3 矩阵 │ │ │ ├── Matrix4.h # 4x4 矩阵 │ │ │ ├── Quaternion.h # 四元数 │ │ │ ├── Transform.h # 变换 │ │ │ ├── Color.h # 颜色 │ │ │ ├── Rect.h # 矩形 │ │ │ ├── Sphere.h # 球体 │ │ │ ├── Box.h # 盒子 │ │ │ ├── Plane.h # 平面 │ │ │ ├── Ray.h # 射线 │ │ │ ├── AABB.h # 轴对齐包围盒 │ │ │ ├── Bounds.h # 包围体 │ │ │ ├── OBB.h # 方向包围盒 │ │ │ ├── Frustum.h # 视锥体 │ │ │ └── Math.h # 数学库统一头文件 │ │ ├── Memory/ # 内存管理模块 │ │ │ ├── Allocator.h # 分配器接口 │ │ │ ├── LinearAllocator.h # 线性分配器 │ │ │ ├── PoolAllocator.h # 内存池分配器 │ │ │ ├── ProxyAllocator.h # 代理分配器 │ │ │ └── MemoryManager.h # 全局内存管理器 │ │ ├── Threading/ # 线程模块 │ │ │ ├── Thread.h # 线程类 │ │ │ ├── Mutex.h # 互斥锁 │ │ │ ├── SpinLock.h # 自旋锁 │ │ │ ├── ReadWriteLock.h # 读写锁 │ │ │ ├── Task.h # 任务基类 │ │ │ ├── LambdaTask.h # Lambda 任务 │ │ │ ├── TaskGroup.h # 任务组 │ │ │ ├── TaskSystem.h # 任务系统 │ │ │ └── Threading.h # 线程模块统一头文件 │ │ ├── Resources/ # 资源管理模块 │ │ │ ├── ResourceTypes.h # 资源类型定义 │ │ │ ├── IResource.h # 资源接口 │ │ │ ├── ResourceHandle.h # 资源句柄 │ │ │ ├── ResourceManager.h # 资源管理器 │ │ │ ├── ResourceCache.h # 资源缓存 │ │ │ ├── ResourcePackage.h # 资源包 │ │ │ ├── ResourceFileSystem.h # 资源文件系统 │ │ │ ├── ResourcePath.h # 资源路径 │ │ │ ├── FileArchive.h # 文件归档 │ │ │ ├── DependencyGraph.h # 依赖图 │ │ │ ├── ImportSettings.h # 导入设置基类 │ │ │ ├── IResourceLoader.h # 资源加载器接口 │ │ │ ├── AsyncLoader.h # 异步加载器 │ │ │ ├── Texture.h # 纹理资源 │ │ │ ├── TextureLoader.h # 纹理加载器 │ │ │ ├── TextureImportSettings.h # 纹理导入设置 │ │ │ ├── Mesh.h # 网格资源 │ │ │ ├── MeshLoader.h # 网格加载器 │ │ │ ├── MeshImportSettings.h # 网格导入设置 │ │ │ ├── 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 # 命令列表抽象 │ │ ├── RHIBuffer.h # 缓冲区抽象 │ │ ├── RHITexture.h # 纹理抽象 │ │ ├── RHIShader.h # 着色器抽象 │ │ ├── RHISampler.h # 采样器抽象 │ │ ├── RHIFence.h # 同步栅栏抽象 │ │ ├── RHISwapChain.h # 交换链抽象 │ │ ├── RHIPipelineState.h # 管线状态抽象 │ │ ├── RHIPipelineLayout.h # 管线布局抽象 │ │ ├── RHIDescriptorPool.h # 描述符池抽象 │ │ ├── RHIDescriptor.h # 描述符抽象 │ │ ├── OpenGL/ # OpenGL 后端实现 │ │ │ ├── OpenGLDevice.h │ │ │ ├── OpenGLCommandQueue.h │ │ │ ├── OpenGLCommandList.h │ │ │ ├── OpenGLSwapChain.h │ │ │ ├── OpenGLPipelineState.h │ │ │ ├── OpenGLBuffer.h │ │ │ ├── OpenGLTexture.h │ │ │ ├── OpenGLShader.h │ │ │ ├── OpenGLSampler.h │ │ │ ├── OpenGLFence.h │ │ │ ├── OpenGLVertexArray.h │ │ │ ├── OpenGLRenderTargetView.h │ │ │ └── OpenGLDepthStencilView.h │ │ └── D3D12/ # DirectX 12 后端实现 │ │ ├── D3D12Device.h │ │ ├── D3D12CommandQueue.h │ │ ├── D3D12CommandAllocator.h │ │ ├── D3D12CommandList.h │ │ ├── D3D12SwapChain.h │ │ ├── D3D12PipelineState.h │ │ ├── D3D12Buffer.h │ │ ├── D3D12Texture.h │ │ ├── D3D12Shader.h │ │ ├── D3D12Sampler.h │ │ ├── D3D12Fence.h │ │ ├── D3D12DescriptorHeap.h │ │ ├── D3D12RootSignature.h │ │ ├── D3D12RenderTargetView.h │ │ ├── D3D12DepthStencilView.h │ │ ├── D3D12ShaderResourceView.h │ │ ├── D3D12UnorderedAccessView.h │ │ ├── D3D12ConstantBufferView.h │ │ ├── D3D12QueryHeap.h │ │ ├── D3D12Screenshot.h │ │ ├── D3D12Types.h │ │ ├── D3D12Enum.h │ │ └── D3D12Common.h │ ├── 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/ # 示例程序 │ ├── D3D12/ # DirectX 12 渲染示例 │ ├── OpenGL/ # OpenGL 渲染示例 │ ├── Music fluctuations/ # 音频可视化示例 │ ├── VolumeRenderer/ # 体积渲染器（NanoVDB） │ └── ui/ # 编辑器 UI 示例 │ ├── 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/ # 构建目录 ``` ## 快速开始 ### 前置要求 - Windows 10/11 - Visual Studio 2019 或更高版本 - CMake 3.15+ ### 构建项目 ```bash # 创建构建目录 mkdir build && cd build # 配置 CMake cmake .. -A x64 # 编译 cmake --build . --config Debug ``` ### 运行测试 ```bash cd build/tests ctest -C Debug --output-on-failure ``` 或直接运行测试可执行文件： ```bash build/tests/containers/Debug/xcengine_containers_tests.exe build/tests/memory/Debug/xcengine_memory_tests.exe 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**: 动态字符串类，支持常用字符串操作 - **Array**: 模板动态数组，自动内存管理 - **HashMap**: 模板哈希表，支持自定义键类型 ### Core（核心基础） - **Types**: 基础类型别名（int8、uint32 等） - **RefCounted**: 引用计数基类，支持多线程安全释放 - **SmartPtr**: 智能指针实现（Ref、UniqueRef） - **Event**: 事件系统，支持订阅/发布模式 - **FileWriter**: 文件写入工具 ### Debug（调试与日志） - **Logger**: 分级日志系统（Info、Warning、Error） - **ConsoleLogSink**: 控制台日志输出 - **FileLogSink**: 文件日志输出 - **Profiler**: 性能分析工具 ### Memory（内存管理） - **IAllocator**: 内存分配器接口 - **LinearAllocator**: 线性分配器，适合帧分配 - **PoolAllocator**: 内存池分配器，适合固定大小对象 - **ProxyAllocator**: 代理分配器，跟踪内存使用统计 - **MemoryManager**: 全局内存管理器 ### Threading（线程） - **Thread**: 线程封装类 - **Mutex**: 互斥锁 - **SpinLock**: 自旋锁，适合短临界区 - **ReadWriteLock**: 读写锁 - **TaskSystem**: 多线程任务系统 - **Task/TaskGroup**: 任务和任务组管理 ### Math（数学库） - **Vector2/3/4**: 向量运算 - **Matrix3/4**: 矩阵运算 - **Quaternion**: 四元数 - **Transform**: 变换（位姿） - **Color**: 颜色 - **Rect**: 矩形 - **Sphere/Box/Plane**: 基本几何体 - **Ray**: 射线 - **AABB/Bounds/OBB**: 包围体 - **Frustum**: 视锥体 ### Resources（资源管理） - **ResourceManager**: 全局资源管理器，资源加载/卸载 - **ResourceCache**: 资源缓存，支持引用计数 - **ResourceHandle**: 资源句柄，安全引用资源 - **ResourcePackage**: 资源包批量管理 - **AsyncLoader**: 异步资源加载器 - **ImportSettings**: 资源导入设置（纹理/网格/材质） - **IResourceLoader**: 资源加载器接口 - **Texture/Mesh/Shader/Material/AudioClip**: 各类资源类型 ### Scene（场景管理） - **Scene**: 场景类，管理场景内的所有游戏对象 - **SceneManager**: 场景管理器，处理场景切换 ### RHI（渲染硬件接口） XCEngine 采用 RHI（Render Hardware Interface）抽象层设计，支持多渲染后端。 #### 设计原则 - **求同存异**: 提取各 API 共同特性，统一抽象接口 - **分层抽象**: 核心抽象层 → 后端实现层 → 平台适配层 - **特性降级**: 后端不支持的特性优雅降级 - **底层逃逸**: 后端特有方法通过重载暴露 #### 抽象接口 - **RHIDevice**: 渲染设备抽象 - **RHICommandQueue**: 命令队列抽象 - **RHICommandList**: 命令列表抽象 - **RHISwapChain**: 交换链抽象 - **RHIPipelineState**: 渲染管线状态抽象 - **RHIBuffer/RHITexture**: 资源抽象 - **RHIShader**: 着色器抽象 - **RHISampler**: 采样器抽象 - **RHIFence**: 同步栅栏抽象 #### 后端实现 - **OpenGL 后端**: OpenGL 4.6+ 支持 - **D3D12 后端**: DirectX 12 支持 ## 测试覆盖 | 模块 | 测试用例数 | |------|-----------| | Containers | 51+ | | Memory | 19 | | Threading | 13 | | 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 后端。 ### D3D12 / OpenGL 跨平台渲染示例，展示如何： - 初始化 RHI 渲染环境（支持 D3D12/OpenGL） - 加载和渲染静态网格 - 纹理映射 - 常量缓冲区更新 ### VolumeRenderer XCEngine 的体积渲染模块，基于 NanoVDB 实现云、烟雾等体积数据的实时渲染： - NanoVDB 格式体积数据加载 - 光线步进（Ray Marching）渲染 - HDDA 空间跳跃加速 - 体积阴影（Volumetric Shadow） - 动态光照参数调节 ### Music fluctuations 音频可视化示例，基于 FFT 实时分析音频频谱： - 音频播放与 FFT 分析 - 频谱可视化渲染 - 音频与视觉效果同步 ### UI Editor Unity 风格的编辑器 UI，基于 ImGui 实现： - 场景层级面板 - 属性检查器 - 游戏视图与场景视图 - 项目资源浏览器 - 控制台日志面板 ## 文档 API 文档位于 `docs/api/` 目录，包含各模块的完整 API 参考。 详细设计文档请参考 `docs/plan/` 目录。 ## 许可证 MIT License