docs: refresh readme for current rhi status
This commit is contained in:
678
README.md
678
README.md
@@ -1,602 +1,186 @@
|
|||||||
# XCEngine
|
# XCEngine
|
||||||
|
|
||||||
基于 DirectX 12 的模块化游戏引擎，支持体积渲染、跨平台渲染后端和核心模块单元测试。
|
XCEngine 是一个模块化的 C++ 游戏引擎工程，当前以 RHI 抽象层为核心推进渲染能力建设。
|
||||||
|
目前代码库已经具备可用的 D3D12 / OpenGL 双后端 RHI 基线，并配有单元测试与跨后端集成测试，已经可以作为后续基础渲染管线开发的支撑层继续向上推进。
|
||||||
|
|
||||||
## 项目概述
|
## 当前状态
|
||||||
|
|
||||||
XCEngine 是一个正在开发中的模块化 C++ 游戏引擎，采用 RHI（Render Hardware Interface）抽象层设计，支持 DirectX 12 和 OpenGL 4.6+ 多种渲染 API。项目采用模块化设计，包含核心库、示例程序和单元测试。
|
- 构建系统基于 CMake，测试系统基于 Google Test / CTest。
|
||||||
|
- RHI 抽象层当前重点支持 `D3D12` 和 `OpenGL` 两套后端。
|
||||||
|
- RHI 抽象层已完成一轮针对 `pipeline layout`、`descriptor set`、`set-aware binding`、`shader`、`compute/UAV` 路径的系统性收敛。
|
||||||
|
- 抽象层集成测试目前覆盖 `minimal`、`triangle`、`quad`、`sphere` 四个场景。
|
||||||
|
- 每个 RHI 抽象层集成测试场景只维护一张基准图 `GT.ppm`，D3D12 与 OpenGL 生成图都与同一张 GT 图进行比对。
|
||||||
|
- 以当前状态，RHI 已经适合作为“先开做基础渲染管线，再由上层反向驱动继续完善”的工程基线。
|
||||||
|
|
||||||
## 技术栈
|
## RHI 设计原则
|
||||||
|
|
||||||
- **渲染 API**: DirectX 12, OpenGL 4.6+
|
RHI 模块遵循 [`docs/plan/end/RHI模块设计与实现/RHI模块总览.md`](docs/plan/end/RHI模块设计与实现/RHI模块总览.md) 中的核心理念：
|
||||||
- **语言**: C++17
|
|
||||||
- **构建系统**: CMake 3.15+
|
|
||||||
- **测试框架**: Google Test
|
|
||||||
- **UI**: ImGui（用于编辑器）
|
|
||||||
|
|
||||||
## 项目结构
|
- 求同存异：优先抽取后端共性，避免把上层绑死在单一图形 API 上。
|
||||||
|
- 分层抽象：上层功能系统 -> 渲染管线 -> RHI -> 后端 API。
|
||||||
|
- 特性降级：后端能力不一致时，优先通过能力检测与合理降级维持统一接口。
|
||||||
|
- 谨慎逃逸：只有在抽象层无法表达时，才考虑后端特化，而不是让上层直接依赖原生 API。
|
||||||
|
|
||||||
```
|
当前更强调的一条实践约束是：
|
||||||
|
|
||||||
|
- 如果抽象层测试为了“能跑过”而不得不依赖后端私有接口，优先修 RHI 本身，而不是给测试开后门。
|
||||||
|
|
||||||
|
## 近期 RHI 整理结果
|
||||||
|
|
||||||
|
最近一轮 RHI 清理与重构，已经把以下关键问题收敛到统一行为：
|
||||||
|
|
||||||
|
- `pipeline layout` 负责拥有并管理 descriptor set 元数据，而不是把布局信息分散在各处。
|
||||||
|
- D3D12 / OpenGL 两个后端的 descriptor 绑定都已经是 `set-aware` 的，并正确处理 `firstSet`。
|
||||||
|
- OpenGL 路径下，来自内存源码的 GLSL 编译不再依赖意外的 `NUL` 终止。
|
||||||
|
- OpenGL 单 shader 编译路径现在会正确记录 `ShaderType`，计算着色器不再被错误标记为 `Vertex`。
|
||||||
|
- OpenGL 的 compute/UAV 绑定路径已经有真实 dispatch + 回读验证，不再只是状态级别的伪验证。
|
||||||
|
- 抽象层集成测试的 GT 管理已经统一为“每场景一张 GT，双后端都与同一 GT 比对”。
|
||||||
|
|
||||||
|
这意味着当前 RHI 的重点不再是“补最基础可用性”，而是“在做渲染管线的过程中继续按真实需求向前演进”。
|
||||||
|
|
||||||
|
## 仓库结构
|
||||||
|
|
||||||
|
```text
|
||||||
XCEngine/
|
XCEngine/
|
||||||
├── engine/ # 核心引擎库
|
├─ engine/ # 引擎静态库，包含 Core / RHI / Resources / Scene 等模块
|
||||||
│ ├── include/XCEngine/
|
├─ editor/ # 编辑器程序
|
||||||
│ │ ├── Audio/ # 音频系统
|
├─ tests/ # 单元测试与集成测试
|
||||||
│ │ │ ├── AudioSystem.h # 音频系统主类
|
├─ mvs/ # 示例与实验性程序
|
||||||
│ │ │ ├── AudioTypes.h # 音频类型定义
|
├─ docs/ # 设计文档与 API 文档
|
||||||
│ │ │ ├── AudioConfig.h # 音频配置
|
└─ CMakeLists.txt
|
||||||
│ │ │ ├── AudioMixer.h # 音频混音器
|
|
||||||
│ │ │ ├── HRTF.h # HRTF 空间音频
|
|
||||||
│ │ │ ├── FFTFilter.h # FFT 滤波器
|
|
||||||
│ │ │ ├── Reverbation.h # 混响效果
|
|
||||||
│ │ │ ├── Equalizer.h # 均衡器
|
|
||||||
│ │ │ ├── IAudioEffect.h # 音频效果接口
|
|
||||||
│ │ │ ├── IAudioBackend.h # 音频后端接口
|
|
||||||
│ │ │ └── WindowsAudioBackend.h # Windows 音频后端
|
|
||||||
│ │ ├── Components/ # 游戏组件系统
|
|
||||||
│ │ │ ├── Component.h # 组件基类
|
|
||||||
│ │ │ ├── GameObject.h # 游戏对象
|
|
||||||
│ │ │ ├── TransformComponent.h # 变换组件
|
|
||||||
│ │ │ ├── AudioSourceComponent.h # 音频源组件
|
|
||||||
│ │ │ └── AudioListenerComponent.h # 音频监听器组件
|
|
||||||
│ │ ├── Core/ # 核心基础模块
|
|
||||||
│ │ │ ├── Asset/ # 资源系统核心
|
|
||||||
│ │ │ │ ├── IResource.h # 资源接口
|
|
||||||
│ │ │ │ ├── ResourceTypes.h # 资源类型定义
|
|
||||||
│ │ │ │ ├── ResourceHandle.h # 资源句柄
|
|
||||||
│ │ │ │ ├── ResourceManager.h # 资源管理器
|
|
||||||
│ │ │ │ ├── ResourceCache.h # 资源缓存
|
|
||||||
│ │ │ │ ├── AsyncLoader.h # 异步加载器
|
|
||||||
│ │ │ │ ├── ResourceDependencyGraph.h # 依赖图
|
|
||||||
│ │ │ │ └── ImportSettings.h # 导入设置基类
|
|
||||||
│ │ │ ├── IO/ # IO 系统
|
|
||||||
│ │ │ │ ├── IResourceLoader.h # 资源加载器接口
|
|
||||||
│ │ │ │ ├── ResourceFileSystem.h # 资源文件系统
|
|
||||||
│ │ │ │ ├── ResourcePath.h # 资源路径
|
|
||||||
│ │ │ │ ├── FileArchive.h # 文件归档
|
|
||||||
│ │ │ │ └── ResourcePackage.h # 资源包
|
|
||||||
│ │ │ ├── Containers/ # 容器模块
|
|
||||||
│ │ │ │ ├── Array.h # 动态数组
|
|
||||||
│ │ │ │ ├── String.h # 字符串类
|
|
||||||
│ │ │ │ ├── HashMap.h # 哈希表
|
|
||||||
│ │ │ │ └── Containers.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 # 数学库统一头文件
|
|
||||||
│ │ │ ├── Layer.h # 层级
|
|
||||||
│ │ │ ├── LayerStack.h # 层级栈
|
|
||||||
│ │ │ ├── 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 # 性能分析
|
|
||||||
│ │ ├── 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 # 线程模块统一头文件
|
|
||||||
│ │ ├── Platform/ # 平台抽象层
|
|
||||||
│ │ │ ├── PlatformTypes.h # 平台类型
|
|
||||||
│ │ │ ├── IPlatform.h # 平台接口
|
|
||||||
│ │ │ ├── IWindow.h # 窗口接口
|
|
||||||
│ │ │ ├── IFileSystem.h # 文件系统接口
|
|
||||||
│ │ │ ├── IClock.h # 时钟接口
|
|
||||||
│ │ │ ├── IDynamicLibrary.h # 动态库接口
|
|
||||||
│ │ │ ├── IDisplayEnumerator.h # 显示枚举接口
|
|
||||||
│ │ │ ├── GameTime.h # 游戏时间
|
|
||||||
│ │ │ ├── Window.h # 窗口类
|
|
||||||
│ │ │ ├── Windows/ # Windows 平台实现
|
|
||||||
│ │ │ │ ├── WindowsWindow.h
|
|
||||||
│ │ │ │ └── WindowsInputModule.h
|
|
||||||
│ │ │ ├── Linux/ # Linux 平台实现
|
|
||||||
│ │ │ ├── Android/ # Android 平台实现
|
|
||||||
│ │ │ └── macOS/ # macOS 平台实现
|
|
||||||
│ │ ├── Input/ # 输入模块
|
|
||||||
│ │ │ ├── InputTypes.h # 输入类型
|
|
||||||
│ │ │ ├── InputEvent.h # 输入事件
|
|
||||||
│ │ │ ├── InputAxis.h # 输入轴
|
|
||||||
│ │ │ ├── InputModule.h # 输入模块基类
|
|
||||||
│ │ │ └── InputManager.h # 输入管理器
|
|
||||||
│ │ ├── Resources/ # 资源管理模块 (按类型分目录)
|
|
||||||
│ │ │ ├── Texture/ # 纹理资源
|
|
||||||
│ │ │ │ ├── Texture.h
|
|
||||||
│ │ │ │ ├── TextureLoader.h
|
|
||||||
│ │ │ │ └── TextureImportSettings.h
|
|
||||||
│ │ │ ├── Mesh/ # 网格资源
|
|
||||||
│ │ │ │ ├── Mesh.h
|
|
||||||
│ │ │ │ ├── MeshLoader.h
|
|
||||||
│ │ │ │ └── MeshImportSettings.h
|
|
||||||
│ │ │ ├── Shader/ # 着色器资源
|
|
||||||
│ │ │ │ ├── Shader.h
|
|
||||||
│ │ │ │ └── ShaderLoader.h
|
|
||||||
│ │ │ ├── Material/ # 材质资源
|
|
||||||
│ │ │ │ ├── Material.h
|
|
||||||
│ │ │ │ └── MaterialLoader.h
|
|
||||||
│ │ │ ├── AudioClip/ # 音频资源
|
|
||||||
│ │ │ │ ├── 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 # 描述符池抽象
|
|
||||||
│ │ ├── RHIDescriptorSet.h # 描述符集抽象
|
|
||||||
│ │ ├── RHIRenderPass.h # 渲染通道抽象
|
|
||||||
│ │ ├── RHIFramebuffer.h # 帧缓冲抽象
|
|
||||||
│ │ ├── RHIResource.h # 资源基类
|
|
||||||
│ │ ├── RHIResourceView.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
|
|
||||||
│ │ │ ├── OpenGLFramebuffer.h
|
|
||||||
│ │ │ ├── OpenGLRenderPass.h
|
|
||||||
│ │ │ ├── OpenGLResourceView.h
|
|
||||||
│ │ │ ├── OpenGLDescriptorPool.h
|
|
||||||
│ │ │ ├── OpenGLDescriptorSet.h
|
|
||||||
│ │ │ ├── OpenGLTextureUnitAllocator.h
|
|
||||||
│ │ │ ├── OpenGLUniformBufferManager.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
|
|
||||||
│ │ ├── D3D12DescriptorSet.h
|
|
||||||
│ │ ├── D3D12RootSignature.h
|
|
||||||
│ │ ├── D3D12PipelineLayout.h
|
|
||||||
│ │ ├── D3D12RenderTargetView.h
|
|
||||||
│ │ ├── D3D12DepthStencilView.h
|
|
||||||
│ │ ├── D3D12ShaderResourceView.h
|
|
||||||
│ │ ├── D3D12UnorderedAccessView.h
|
|
||||||
│ │ ├── D3D12ConstantBufferView.h
|
|
||||||
│ │ ├── D3D12ResourceView.h
|
|
||||||
│ │ ├── D3D12QueryHeap.h
|
|
||||||
│ │ ├── D3D12RenderPass.h
|
|
||||||
│ │ ├── D3D12Framebuffer.h
|
|
||||||
│ │ ├── D3D12Screenshot.h
|
|
||||||
│ │ ├── D3D12Types.h
|
|
||||||
│ │ ├── D3D12Enums.h
|
|
||||||
│ │ └── D3D12Common.h
|
|
||||||
│ ├── src/ # 实现文件
|
|
||||||
│ │ ├── Audio/
|
|
||||||
│ │ ├── Containers/
|
|
||||||
│ │ ├── Core/
|
|
||||||
│ │ │ ├── Asset/ # Core/Asset 实现
|
|
||||||
│ │ │ └── IO/ # Core/IO 实现
|
|
||||||
│ │ ├── Debug/
|
|
||||||
│ │ ├── Math/
|
|
||||||
│ │ ├── Memory/
|
|
||||||
│ │ ├── Threading/
|
|
||||||
│ │ ├── Platform/
|
|
||||||
│ │ │ └── Windows/
|
|
||||||
│ │ ├── Input/
|
|
||||||
│ │ ├── Resources/
|
|
||||||
│ │ │ ├── Texture/
|
|
||||||
│ │ │ ├── Mesh/
|
|
||||||
│ │ │ ├── Shader/
|
|
||||||
│ │ │ ├── Material/
|
|
||||||
│ │ │ └── AudioClip/
|
|
||||||
│ │ ├── Scene/
|
|
||||||
│ │ └── RHI/
|
|
||||||
│ │ ├── D3D12/
|
|
||||||
│ │ ├── OpenGL/
|
|
||||||
│ │ └── RHIFactory.cpp
|
|
||||||
│ └── third_party/ # 第三方库
|
|
||||||
│ ├── kissfft/ # FFT 库
|
|
||||||
│ ├── stb/ # 图像处理库 (stb_image, stb_image_write)
|
|
||||||
│ ├── GLAD/ # OpenGL 加载器
|
|
||||||
│ └── renderdoc/ # RenderDoc 调试库
|
|
||||||
│
|
|
||||||
├── editor/ # 编辑器 UI 应用程序
|
|
||||||
│ ├── src/ # 编辑器源代码
|
|
||||||
│ │ ├── Application.cpp/h # 编辑器应用入口
|
|
||||||
│ │ ├── main.cpp # 主函数
|
|
||||||
│ │ ├── Core/ # 编辑器核心
|
|
||||||
│ │ ├── Layers/ # 编辑器层级
|
|
||||||
│ │ ├── Managers/ # 管理器
|
|
||||||
│ │ ├── panels/ # 编辑器面板
|
|
||||||
│ │ └── UI/ # UI 控件
|
|
||||||
│ ├── bin/ # 资源文件和可执行文件
|
|
||||||
│ └── build/ # 构建目录
|
|
||||||
│
|
|
||||||
├── tests/ # 单元测试
|
|
||||||
│ ├── math/ # 数学库测试
|
|
||||||
│ ├── containers/ # 容器测试
|
|
||||||
│ ├── memory/ # 内存管理测试
|
|
||||||
│ ├── threading/ # 线程模块测试
|
|
||||||
│ ├── debug/ # 调试模块测试
|
|
||||||
│ ├── core/ # 核心模块测试
|
|
||||||
│ │ ├── Asset/ # Core/Asset 模块测试
|
|
||||||
│ │ └── IO/ # Core/IO 模块测试
|
|
||||||
│ ├── Components/ # 组件测试
|
|
||||||
│ ├── Scene/ # 场景测试
|
|
||||||
│ ├── Resources/ # 资源管理测试
|
|
||||||
│ │ ├── Texture/
|
|
||||||
│ │ ├── Mesh/
|
|
||||||
│ │ ├── Material/
|
|
||||||
│ │ ├── Shader/
|
|
||||||
│ │ └── AudioClip/
|
|
||||||
│ ├── Input/ # 输入模块测试
|
|
||||||
│ └── RHI/ # RHI 抽象层测试
|
|
||||||
│ ├── unit/ # RHI 抽象层单元测试 (10 files)
|
|
||||||
│ ├── D3D12/ # D3D12 后端测试
|
|
||||||
│ │ ├── unit/ # D3D12 单元测试 (14 files)
|
|
||||||
│ │ └── integration/ # D3D12 集成测试 (minimal, quad, sphere, triangle)
|
|
||||||
│ └── OpenGL/ # OpenGL 后端测试
|
|
||||||
│ ├── unit/ # OpenGL 单元测试 (12 files)
|
|
||||||
│ └── integration/ # OpenGL 集成测试 (minimal, quad, sphere, triangle)
|
|
||||||
│
|
|
||||||
├── mvs/ # 示例程序
|
|
||||||
│ ├── D3D12/ # DirectX 12 渲染示例
|
|
||||||
│ ├── OpenGL/ # OpenGL 渲染示例
|
|
||||||
│ ├── Music fluctuations/ # 音频可视化示例
|
|
||||||
│ ├── VolumeRenderer/ # 体积渲染器（NanoVDB）
|
|
||||||
│ ├── RenderDoc/ # RenderDoc 集成示例
|
|
||||||
│ ├── ui/ # 编辑器 UI 示例
|
|
||||||
│ └── Res/ # 示例资源文件
|
|
||||||
│
|
|
||||||
├── docs/ # 文档
|
|
||||||
│ ├── api/ # API 文档
|
|
||||||
│ │ ├── audio/ # 音频系统 API
|
|
||||||
│ │ ├── components/ # 组件系统 API
|
|
||||||
│ │ ├── containers/ # 容器 API
|
|
||||||
│ │ ├── core/ # 核心 API
|
|
||||||
│ │ ├── d3d12/ # D3D12 API
|
|
||||||
│ │ ├── debug/ # 调试 API
|
|
||||||
│ │ ├── math/ # 数学库 API
|
|
||||||
│ │ ├── memory/ # 内存管理 API
|
|
||||||
│ │ ├── resources/ # 资源管理 API
|
|
||||||
│ │ └── main.md # API 文档总索引
|
|
||||||
│ ├── plan/ # 开发计划与架构设计
|
|
||||||
│ └── api-skill.md # API 技能文档
|
|
||||||
│
|
|
||||||
├── 参考/ # 参考资料
|
|
||||||
│ └── Fermion/ # 参考项目
|
|
||||||
│
|
|
||||||
├── build/ # 构建目录
|
|
||||||
│
|
|
||||||
└── imgui.ini # ImGui 配置文件
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
和当前渲染工作最相关的目录：
|
||||||
|
|
||||||
|
- `engine/include/XCEngine/RHI/`
|
||||||
|
- `engine/src/RHI/`
|
||||||
|
- `tests/RHI/unit/`
|
||||||
|
- `tests/RHI/integration/`
|
||||||
|
- `tests/TEST_SPEC.md`
|
||||||
|
|
||||||
|
## 环境要求
|
||||||
|
|
||||||
|
推荐开发环境：
|
||||||
|
|
||||||
|
- Windows 10/11
|
||||||
|
- Visual Studio 2019 或更新版本
|
||||||
|
- CMake 3.15+
|
||||||
|
- Python 3
|
||||||
|
- RHI 抽象层集成测试会调用 `compare_ppm.py` 做 GT 图比对
|
||||||
|
- 可用的 D3D12 和/或 OpenGL 驱动环境
|
||||||
|
|
||||||
## 快速开始
|
## 快速开始
|
||||||
|
|
||||||
### 前置要求
|
### 1. 配置
|
||||||
|
|
||||||
- Windows 10/11
|
如果使用 Visual Studio 生成器：
|
||||||
- Visual Studio 2019 或更高版本
|
|
||||||
- CMake 3.15+
|
|
||||||
|
|
||||||
### 构建项目
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 创建构建目录
|
cmake -S . -B build -A x64
|
||||||
mkdir build && cd build
|
|
||||||
|
|
||||||
# 配置 CMake
|
|
||||||
cmake .. -A x64
|
|
||||||
|
|
||||||
# 编译
|
|
||||||
cmake --build . --config Debug
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 运行测试
|
如果使用 Ninja 等单配置生成器：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd build/tests
|
cmake -S . -B build
|
||||||
ctest -C Debug --output-on-failure
|
|
||||||
```
|
```
|
||||||
|
|
||||||
或直接运行测试可执行文件：
|
### 2. 构建
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
build/tests/containers/Debug/xcengine_containers_tests.exe
|
cmake --build build --config Debug
|
||||||
build/tests/memory/Debug/xcengine_memory_tests.exe
|
|
||||||
build/tests/threading/Debug/xcengine_threading_tests.exe
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 核心模块说明
|
如果只想增量构建当前最关键的 RHI 测试目标：
|
||||||
|
|
||||||
### Audio（音频系统）
|
```bash
|
||||||
|
cmake --build build --config Debug --target rhi_unit_tests
|
||||||
|
cmake --build build --config Debug --target rhi_integration_minimal
|
||||||
|
cmake --build build --config Debug --target rhi_integration_triangle
|
||||||
|
cmake --build build --config Debug --target rhi_integration_quad
|
||||||
|
cmake --build build --config Debug --target rhi_integration_sphere
|
||||||
|
```
|
||||||
|
|
||||||
- **AudioSystem**: 音频系统主类，管理所有音频设备
|
## 测试
|
||||||
- **AudioMixer**: 音频混音器，多通道混合与效果处理
|
|
||||||
- **HRTF**: 头部相关传输函数，支持空间音频定位
|
|
||||||
- **FFTFilter**: 快速傅里叶变换滤波器
|
|
||||||
- **Reverbation**: 混响效果
|
|
||||||
- **Equalizer**: 音频均衡器
|
|
||||||
- **WindowsAudioBackend**: Windows WASAPI 音频后端实现
|
|
||||||
- **AudioSourceComponent**: 音频源组件（用于游戏对象）
|
|
||||||
- **AudioListenerComponent**: 音频监听器组件（用于游戏对象）
|
|
||||||
|
|
||||||
### Components（游戏组件系统）
|
### 运行全部测试
|
||||||
|
|
||||||
- **Component**: 组件基类，提供生命周期管理
|
```bash
|
||||||
- **GameObject**: 游戏对象，支持层级结构
|
ctest --test-dir build -C Debug --output-on-failure
|
||||||
- **TransformComponent**: 变换组件，管理位置、旋转、缩放
|
```
|
||||||
- **AudioSourceComponent**: 音频源组件
|
|
||||||
- **AudioListenerComponent**: 音频监听器组件
|
|
||||||
|
|
||||||
### Containers（容器）
|
### 查看已注册测试
|
||||||
|
|
||||||
- **String**: 动态字符串类，支持常用字符串操作
|
```bash
|
||||||
- **Array**: 模板动态数组，自动内存管理
|
ctest --test-dir build -N -C Debug
|
||||||
- **HashMap**: 模板哈希表，支持自定义键类型
|
```
|
||||||
|
|
||||||
### Core（核心基础）
|
### 运行 RHI 抽象层单元测试
|
||||||
|
|
||||||
- **Types**: 基础类型别名（int8、uint32 等）
|
```bash
|
||||||
- **RefCounted**: 引用计数基类，支持多线程安全释放
|
build\tests\RHI\unit\Debug\rhi_unit_tests.exe
|
||||||
- **SmartPtr**: 智能指针实现（Ref、UniqueRef）
|
```
|
||||||
- **Event**: 事件系统，支持订阅/发布模式
|
|
||||||
- **FileWriter**: 文件写入工具
|
|
||||||
- **Layer/LayerStack**: 层级与层级栈管理
|
|
||||||
|
|
||||||
### Platform（平台抽象层）
|
### 运行 RHI 抽象层集成测试
|
||||||
|
|
||||||
跨平台抽象接口，支持 Windows、Linux、Android、macOS：
|
以 `quad` 为例：
|
||||||
|
|
||||||
- **IPlatform**: 平台接口
|
```bash
|
||||||
- **IWindow**: 窗口接口
|
build\tests\RHI\integration\quad\Debug\rhi_integration_quad.exe --gtest_filter=D3D12/QuadTest.RenderQuad/0
|
||||||
- **IFileSystem**: 文件系统接口
|
build\tests\RHI\integration\quad\Debug\rhi_integration_quad.exe --gtest_filter=OpenGL/QuadTest.RenderQuad/0
|
||||||
- **IClock**: 时钟接口
|
```
|
||||||
- **IDynamicLibrary**: 动态库加载接口
|
|
||||||
- **IDisplayEnumerator**: 显示设备枚举接口
|
|
||||||
- **Window**: 窗口实现类
|
|
||||||
|
|
||||||
### Input（输入模块）
|
截图输出约定：
|
||||||
|
|
||||||
- **InputManager**: 输入管理器
|
- `quad_d3d12.ppm`
|
||||||
- **InputModule**: 输入模块基类
|
- `quad_opengl.ppm`
|
||||||
- **InputEvent**: 输入事件定义
|
- `GT.ppm`
|
||||||
- **InputAxis**: 输入轴配置
|
|
||||||
|
|
||||||
### Debug（调试与日志）
|
两个后端都会与同目录下同一张 `GT.ppm` 比对。
|
||||||
|
|
||||||
- **Logger**: 分级日志系统（Info、Warning、Error）
|
## RHI 测试体系
|
||||||
- **ConsoleLogSink**: 控制台日志输出
|
|
||||||
- **FileLogSink**: 文件日志输出
|
|
||||||
- **Profiler**: 性能分析工具
|
|
||||||
- **RenderDocCapture**: RenderDoc 帧捕获集成，支持 D3D12/OpenGL GPU 调试
|
|
||||||
|
|
||||||
### Memory（内存管理）
|
当前 RHI 测试分为四层：
|
||||||
|
|
||||||
- **IAllocator**: 内存分配器接口
|
| 层级 | 目录 | 目标 |
|
||||||
- **LinearAllocator**: 线性分配器，适合帧分配
|
| --- | --- | --- |
|
||||||
- **PoolAllocator**: 内存池分配器，适合固定大小对象
|
| 抽象层单元测试 | `tests/RHI/unit/` | 验证公共 RHI 接口在双后端上的一致性 |
|
||||||
- **ProxyAllocator**: 代理分配器，跟踪内存使用统计
|
| 抽象层集成测试 | `tests/RHI/integration/` | 用同一套 RHI 抽象代码驱动 D3D12 / OpenGL 完成真实渲染 |
|
||||||
- **MemoryManager**: 全局内存管理器
|
| D3D12 后端测试 | `tests/RHI/D3D12/` | 验证 D3D12 封装自身行为 |
|
||||||
|
| OpenGL 后端测试 | `tests/RHI/OpenGL/` | 验证 OpenGL 封装自身行为 |
|
||||||
|
|
||||||
### Threading（线程）
|
当前已存在的关键 RHI 测试目标：
|
||||||
|
|
||||||
- **Thread**: 线程封装类
|
- `rhi_unit_tests`
|
||||||
- **Mutex**: 互斥锁
|
- `rhi_integration_minimal`
|
||||||
- **SpinLock**: 自旋锁，适合短临界区
|
- `rhi_integration_triangle`
|
||||||
- **ReadWriteLock**: 读写锁
|
- `rhi_integration_quad`
|
||||||
- **TaskSystem**: 多线程任务系统
|
- `rhi_integration_sphere`
|
||||||
- **Task/TaskGroup**: 任务和任务组管理
|
- `rhi_d3d12_tests`
|
||||||
|
- `rhi_opengl_tests`
|
||||||
|
|
||||||
### Math（数学库）
|
更多测试组织与命名规范见 [`tests/TEST_SPEC.md`](tests/TEST_SPEC.md)。
|
||||||
|
|
||||||
- **Vector2/3/4**: 向量运算
|
## 文档入口
|
||||||
- **Matrix3/4**: 矩阵运算
|
|
||||||
- **Quaternion**: 四元数
|
|
||||||
- **Transform**: 变换（位姿）
|
|
||||||
- **Color**: 颜色
|
|
||||||
- **Rect**: 矩形
|
|
||||||
- **Sphere/Box/Plane**: 基本几何体
|
|
||||||
- **Ray**: 射线
|
|
||||||
- **AABB/Bounds**: 包围体
|
|
||||||
- **Frustum**: 视锥体
|
|
||||||
|
|
||||||
### Resources（资源管理）
|
- RHI 总览与设计原则：
|
||||||
|
[`docs/plan/end/RHI模块设计与实现/RHI模块总览.md`](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
|
||||||
|
- 测试规范：
|
||||||
|
[`tests/TEST_SPEC.md`](tests/TEST_SPEC.md)
|
||||||
|
- API 文档：
|
||||||
|
`docs/api/`
|
||||||
|
|
||||||
XCEngine 资源系统采用分层架构：
|
## 当前开发建议
|
||||||
|
|
||||||
#### Core/Asset（资源系统核心）
|
如果你的目标是继续推进引擎渲染能力，建议直接在当前 RHI 之上开始做基础渲染管线，而不是继续闭门补抽象层“理论完整性”。
|
||||||
|
|
||||||
- **IResource**: 资源接口基类
|
推荐策略：
|
||||||
- **ResourceTypes**: 资源类型定义（GUID、状态等）
|
|
||||||
- **ResourceHandle**: 资源句柄，安全引用资源
|
|
||||||
- **ResourceManager**: 全局资源管理器，资源加载/卸载
|
|
||||||
- **ResourceCache**: 资源缓存，支持引用计数
|
|
||||||
- **AsyncLoader**: 异步资源加载器
|
|
||||||
- **ResourceDependencyGraph**: 资源依赖图管理
|
|
||||||
|
|
||||||
#### Core/IO（资源 IO 系统）
|
- 先做最小可运行的基础渲染管线
|
||||||
|
- 始终只依赖公共 RHI 抽象接口
|
||||||
- **IResourceLoader**: 资源加载器接口
|
- 一旦上层逼出真实缺口，回到 RHI 修根因
|
||||||
- **ResourceFileSystem**: 资源文件系统
|
- 每次修 RHI 时同步补单测和集成测试
|
||||||
- **ResourcePath**: 资源路径解析
|
- 始终把“双后端功能不破坏”放在第一优先级
|
||||||
- **FileArchive**: 文件归档支持
|
|
||||||
- **ResourcePackage**: 资源包批量管理
|
|
||||||
|
|
||||||
#### Resources/<Type>（具体资源类型）
|
|
||||||
|
|
||||||
- **Texture**: 纹理资源（Texture.h、TextureLoader.h、TextureImportSettings.h）
|
|
||||||
- **Mesh**: 网格资源（Mesh.h、MeshLoader.h、MeshImportSettings.h）
|
|
||||||
- **Shader**: 着色器资源（Shader.h、ShaderLoader.h）
|
|
||||||
- **Material**: 材质资源（Material.h、MaterialLoader.h）
|
|
||||||
- **AudioClip**: 音频资源（AudioClip.h、AudioLoader.h）
|
|
||||||
|
|
||||||
### Scene（场景管理）
|
|
||||||
|
|
||||||
- **Scene**: 场景类，管理场景内的所有游戏对象
|
|
||||||
- **SceneManager**: 场景管理器，处理场景切换
|
|
||||||
|
|
||||||
### RHI（渲染硬件接口）
|
|
||||||
|
|
||||||
XCEngine 采用 RHI（Render Hardware Interface）抽象层设计，支持多渲染后端。
|
|
||||||
|
|
||||||
#### 设计原则
|
|
||||||
|
|
||||||
- **求同存异**: 提取各 API 共同特性，统一抽象接口
|
|
||||||
- **分层抽象**: 核心抽象层 → 后端实现层 → 平台适配层
|
|
||||||
- **特性降级**: 后端不支持的特性优雅降级
|
|
||||||
- **底层逃逸**: 后端特有方法通过重载暴露
|
|
||||||
|
|
||||||
#### 抽象接口
|
|
||||||
|
|
||||||
- **RHIDevice**: 渲染设备抽象
|
|
||||||
- **RHICommandQueue**: 命令队列抽象
|
|
||||||
- **RHICommandList**: 命令列表抽象
|
|
||||||
- **RHISwapChain**: 交换链抽象
|
|
||||||
- **RHIPipelineState**: 渲染管线状态抽象
|
|
||||||
- **RHIPipelineLayout**: 管线布局抽象
|
|
||||||
- **RHIBuffer/RHITexture**: 资源抽象
|
|
||||||
- **RHIShader**: 着色器抽象
|
|
||||||
- **RHISampler**: 采样器抽象
|
|
||||||
- **RHIFence**: 同步栅栏抽象
|
|
||||||
- **RHIDescriptorPool**: 描述符池抽象
|
|
||||||
- **RHIDescriptorSet**: 描述符集抽象
|
|
||||||
- **RHIRenderPass**: 渲染通道抽象
|
|
||||||
- **RHIFramebuffer**: 帧缓冲抽象
|
|
||||||
- **RHIResourceView**: 资源视图抽象
|
|
||||||
|
|
||||||
#### 后端实现
|
|
||||||
|
|
||||||
- **OpenGL 后端**: OpenGL 4.6+ 支持
|
|
||||||
- **D3D12 后端**: DirectX 12 支持
|
|
||||||
|
|
||||||
## 测试覆盖
|
|
||||||
|
|
||||||
| 模块 | 测试用例数 |
|
|
||||||
|------|-----------|
|
|
||||||
| Math | ~4 |
|
|
||||||
| Containers | ~3 |
|
|
||||||
| Memory | ~3 |
|
|
||||||
| Threading | ~3 |
|
|
||||||
| Debug | ~3 |
|
|
||||||
| Core | ~10 |
|
|
||||||
| Components | ~3 |
|
|
||||||
| Scene | ~2 |
|
|
||||||
| Resources | ~12 |
|
|
||||||
| Input | ~2 |
|
|
||||||
| RHI/unit | ~10 |
|
|
||||||
| RHI/D3D12 | ~18 (unit + integration) |
|
|
||||||
| RHI/OpenGL | ~16 (unit + integration) |
|
|
||||||
|
|
||||||
## mvs 示例程序
|
|
||||||
|
|
||||||
mvs（Multiple Version Samples）展示游戏引擎的各类功能。所有示例均基于 RHI 抽象层开发，可无缝切换 DirectX 12 或 OpenGL 后端。
|
|
||||||
|
|
||||||
### D3D12 / OpenGL
|
|
||||||
|
|
||||||
跨平台渲染示例，展示如何：
|
|
||||||
- 初始化 RHI 渲染环境（支持 D3D12/OpenGL）
|
|
||||||
- 加载和渲染静态网格
|
|
||||||
- 纹理映射
|
|
||||||
- 常量缓冲区更新
|
|
||||||
|
|
||||||
### RenderDoc
|
|
||||||
|
|
||||||
D3D12 + RenderDoc 集成示例，展示如何使用 RenderDoc API 进行 GPU 帧捕获和调试：
|
|
||||||
- 动态加载 renderdoc.dll
|
|
||||||
- 帧捕获 API（BeginCapture/EndCapture/TriggerCapture）
|
|
||||||
- 捕获文件路径和注释设置
|
|
||||||
|
|
||||||
> 注意：renderdoc.dll 需单独放置于 `engine/third_party/renderdoc/renderdoc.dll`
|
|
||||||
|
|
||||||
### VolumeRenderer
|
|
||||||
|
|
||||||
XCEngine 的体积渲染模块，基于 NanoVDB 实现云、烟雾等体积数据的实时渲染：
|
|
||||||
- NanoVDB 格式体积数据加载
|
|
||||||
- 光线步进（Ray Marching）渲染
|
|
||||||
- HDDA 空间跳跃加速
|
|
||||||
- 体积阴影（Volumetric Shadow）
|
|
||||||
- 动态光照参数调节
|
|
||||||
|
|
||||||
### Music fluctuations
|
|
||||||
|
|
||||||
音频可视化示例，基于 FFT 实时分析音频频谱：
|
|
||||||
- 音频播放与 FFT 分析
|
|
||||||
- 频谱可视化渲染
|
|
||||||
- 音频与视觉效果同步
|
|
||||||
|
|
||||||
### Editor UI
|
|
||||||
|
|
||||||
Unity 风格的编辑器 UI，基于 ImGui 实现：
|
|
||||||
- 场景层级面板
|
|
||||||
- 属性检查器
|
|
||||||
- 游戏视图与场景视图
|
|
||||||
- 项目资源浏览器
|
|
||||||
- 控制台日志面板
|
|
||||||
|
|
||||||
## 文档
|
|
||||||
|
|
||||||
API 文档位于 `docs/api/` 目录，包含各模块的完整 API 参考。
|
|
||||||
|
|
||||||
详细设计文档请参考 `docs/plan/` 目录。
|
|
||||||
|
|
||||||
## 许可证
|
## 许可证
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user