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      # 音频混音器
│   │   │   ├── HRTF.h            # HRTF 空间音频
│   │   │   ├── FFTFilter.h       # FFT 滤波器
│   │   │   ├── Reverbation.h     # 混响效果
│   │   │   ├── Equalizer.h       # 均衡器
│   │   │   ├── IAudioEffect.h    # 音频效果接口
│   │   │   ├── WASAPI/           # WASAPI 后端实现
│   │   │   └── IAudioBackend.h   # 音频后端接口
│   │   ├── Components/           # 游戏组件系统
│   │   │   ├── Component.h       # 组件基类
│   │   │   ├── GameObject.h      # 游戏对象
│   │   │   ├── TransformComponent.h # 变换组件
│   │   │   ├── AudioSourceComponent.h # 音频源组件
│   │   │   └── AudioListenerComponent.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          # 包围体
│   │   │   └── 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      # 任务系统
│   │   │   ├── TaskSystemConfig.h # 任务系统配置
│   │   │   └── Threading.h       # 线程模块统一头文件
│   │   ├── Resources/           # 资源管理模块
│   │   │   ├── ResourceTypes.h   # 资源类型定义
│   │   │   ├── IResource.h       # 资源接口
│   │   │   ├── ResourceHandle.h  # 资源句柄
│   │   │   ├── ResourceManager.h # 资源管理器
│   │   │   ├── ResourceCache.h   # 资源缓存
│   │   │   ├── ResourcePackage.h # 资源包
│   │   │   ├── ResourceFileSystem.h # 资源文件系统
│   │   │   ├── ResourcePath.h    # 资源路径
│   │   │   ├── FileArchive.h     # 文件归档
│   │   │   ├── ResourceDependencyGraph.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 # 描述符池抽象
│   │       ├── 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
│   │       │   └── OpenGLScreenshot.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
│   │           ├── D3D12Enum.h
│   │           ├── D3D12Types.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+

构建项目

# 创建构建目录
mkdir build && cd build

# 配置 CMake
cmake .. -A x64

# 编译
cmake --build . --config Debug

运行测试

cd build/tests
ctest -C Debug --output-on-failure

或直接运行测试可执行文件：

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