XCEngine/README.md

# 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/
│   │   ├── Containers/            # 容器模块
│   │   │   ├── String.h          # 字符串类
│   │   │   ├── Array.h           # 动态数组
│   │   │   └── HashMap.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 # 任务系统配置
│   │   ├── Math/                 # 数学库
│   │   │   ├── Vector.h
│   │   │   ├── Matrix.h
│   │   │   ├── Quaternion.h
│   │   │   └── ...
│   │   ├── RHI/                  # 渲染硬件接口抽象层
│   │   │   ├── RHIDevice.h
│   │   │   ├── RHICommandQueue.h
│   │   │   ├── RHICommandList.h
│   │   │   ├── RHISwapChain.h
│   │   │   ├── RHIPipelineState.h
│   │   │   ├── RHIBuffer.h
│   │   │   ├── RHITexture.h
│   │   │   ├── RHIShader.h
│   │   │   ├── RHISampler.h
│   │   │   ├── RHIFence.h
│   │   │   ├── RHITypes.h
│   │   │   ├── RHICapabilities.h
│   │   │   ├── RHIEnums.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
│   │   │       ├── D3D12CommandList.h
│   │   │       ├── D3D12CommandAllocator.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
│   │   └── Core/                 # 核心模块
│   │
│   └── src/                      # 实现文件
│       ├── Containers/
│       ├── Memory/
│       ├── Threading/
│       ├── Math/
│       └── RHI/
│
├── tests/                         # 单元测试
│   ├── containers/               # 容器测试
│   ├── memory/                  # 内存管理测试
│   ├── threading/               # 线程模块测试
│   ├── core/                    # 核心模块测试
│   ├── math/                    # 数学库测试
│   └── RHI/                     # RHI 抽象层测试
│       ├── OpenGL/              # OpenGL 后端测试
│       └── D3D12/                # D3D12 后端测试
│
├── MVS/                         # 多个示例版本（开发中）
│   ├── HelloEarth/              # 基础渲染示例
│   └── VolumeRenderer/          # 体积渲染器
│
├── docs/                         # 设计文档
│   ├── XCEngine渲染引擎架构设计.md
│   └── ...
│
└── 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
```

## 核心模块说明

### Containers（容器）

- **String**: 动态字符串类，支持常用字符串操作
- **Array**: 模板动态数组，自动内存管理
- **HashMap**: 模板哈希表，支持自定义键类型

### Memory（内存管理）

- **IAllocator**: 内存分配器接口
- **LinearAllocator**: 线性分配器，适合帧分配
- **PoolAllocator**: 内存池分配器，适合固定大小对象
- **ProxyAllocator**: 代理分配器，跟踪内存使用统计
- **MemoryManager**: 全局内存管理器

### Threading（线程）

- **Thread**: 线程封装类
- **Mutex**: 互斥锁
- **SpinLock**: 自旋锁，适合短临界区
- **ReadWriteLock**: 读写锁
- **TaskSystem**: 多线程任务系统
- **Task/TaskGroup**: 任务和任务组管理

### Math（数学库）

- **Vector**: 向量运算
- **Matrix**: 矩阵运算
- **Quaternion**: 四元数
- **Transform**: 变换
- **Color**: 颜色
- **Frustum**: 视锥体
- **Bounds**: 边界框

### RHI（渲染硬件接口）

XCEngine 采用 RHI（Render Hardware Interface）抽象层设计，支持多渲染后端。

#### 设计原则

- **求同存异**: 提取各 API 共同特性，统一抽象接口
- **分层抽象**: 核心抽象层 → 后端实现层 → 平台适配层
- **特性降级**: 后端不支持的特性优雅降级
- **底层逃逸**: 后端特有方法通过重载暴露

#### 抽象接口

- **RHIDevice**: 渲染设备抽象
- **RHICommandQueue**: 命令队列抽象
- **RHICommandList**: 命令列表抽象
- **RHISwapChain**: 交换链抽象
- **RHIPipelineState**: 渲染管线状态抽象
- **RHIBuffer/RHITexture**: 资源抽象
- **RHIShader**: 着色器抽象
- **RHISampler**: 采样器抽象
- **RHIFence**: 同步栅栏抽象

#### 后端实现

- **OpenGL 后端**: OpenGL 4.6+ 支持
- **D3D12 后端**: DirectX 12 支持

#### 测试覆盖

- OpenGL 后端: 41 个测试用例通过
- D3D12 后端: 编译通过

## 测试覆盖

- Containers: 51+ 测试用例
- Memory: 19 测试用例
- Threading: 13 测试用例
- Math: 通过
- RHI (OpenGL): 41 测试用例通过
- RHI (D3D12): 编译通过

## MVS 示例版本

MVS（Multiple Version Samples）是项目的渲染示例部分，展示各种渲染技术。所有示例均基于 RHI 抽象层开发，可无缝切换 DirectX 12 或 OpenGL 后端。

### HelloEarth（开发中）

基础的跨平台渲染示例，展示如何：
- 初始化 RHI 渲染环境（支持 D3D12/OpenGL）
- 加载和渲染静态网格
- 使用几何着色器
- 纹理映射
- 常量缓冲区更新

### VolumeRenderer（开发中）

基于 NanoVDB 的体积渲染器，支持：
- NanoVDB 格式体积数据加载
- 光线步进（Ray Marching）渲染
- HDDA 空间跳跃加速
- 体积阴影
- 多种渲染参数配置

## 文档

更多详细设计文档请参考 `docs/` 目录。

## 许可证

MIT License