# RoomRenderer

**Repository Path**: szzhoujiarui/RoomRenderer

## Basic Information

- **Project Name**: RoomRenderer
- **Description**: Vulkan Ray Tracing Room Renderer
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-21
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[English](README.en.md)

![RoomRenderer portfolio banner](docs/assets/banner.png)

# RoomRenderer：Vulkan 光线追踪室内渲染器

> 源码可验证的 C++20/Vulkan RT 工程案例；Windows、Vulkan RT GPU、画面结果与性能待实机验证。

## 客户价值

RoomRenderer 展示室内渲染器从场景几何、Vulkan 光线追踪、栅格回退、自定义受启发原型源码模块到 GPU 诊断与截图落盘的工程组织方式。案例重点是可审查的实现路径和明确的验收边界，便于技术团队评估代码结构、图形 API 使用和后续实机验证成本。

本仓库当前可交付的是源码证据。运行画面、性能数字、硬件兼容性和 Windows 构建结果均属于后续验收项。

## 源码证据说明

本文采用三类声明：

| 声明类型 | 含义 |
|---|---|
| 源码已实现 | 指定源码中存在可审查的 Vulkan 调用、资源或命令记录逻辑 |
| 自定义受启发原型源码模块 | 项目内 compute shader 路径借鉴公开技术思路，尚未完成 shader 编译验证，不代表集成厂商 SDK |
| 待实机验证 | 需要 Windows、Vulkan RT GPU 和运行产物才能确认的构建、画质、性能与兼容性 |

关键证据入口包括 [`src/renderer/RayTracer.cpp`](src/renderer/RayTracer.cpp)、[`src/renderer/Rasterizer.cpp`](src/renderer/Rasterizer.cpp)、[`src/denoise/Denoiser.cpp`](src/denoise/Denoiser.cpp)、[`src/upscaler/FSR3Upscaler.cpp`](src/upscaler/FSR3Upscaler.cpp)、[`src/upscaler/XeSSUpscaler.cpp`](src/upscaler/XeSSUpscaler.cpp)、[`src/debug/GpuTimer.h`](src/debug/GpuTimer.h) 和 [`src/debug/Screenshot.cpp`](src/debug/Screenshot.cpp)。

## 渲染流程

![Renderer data flow](docs/assets/render-pipeline.png)

1. 场景网格和材质进入渲染资源准备阶段。
2. [`src/renderer/RayTracer.cpp`](src/renderer/RayTracer.cpp) 上传几何并构建 BLAS/TLAS，创建光线追踪 pipeline 与 SBT，随后通过 `vkCmdTraceRaysKHR` 发射光线。
3. [`src/renderer/Rasterizer.cpp`](src/renderer/Rasterizer.cpp) 提供 graphics pipeline、descriptor 绑定和 `vkCmdDrawIndexed` 栅格绘制路径。
4. [`src/upscaler/FSR3Upscaler.cpp`](src/upscaler/FSR3Upscaler.cpp) 与 [`src/upscaler/XeSSUpscaler.cpp`](src/upscaler/XeSSUpscaler.cpp) 属于自定义受启发原型源码模块，尚未完成 shader 编译验证，尚未接入主渲染循环，也未集成官方 SDK；其画质结果不声明与厂商方案同等。
5. [`src/debug/GpuTimer.h`](src/debug/GpuTimer.h) 提供 Vulkan timestamp query；[`src/debug/Screenshot.cpp`](src/debug/Screenshot.cpp) 负责图像读回、Reinhard tone mapping、gamma 校正和 PNG 写入。截图仅在 RT 分支执行，raster 分支会清除截图请求。

## 能力证据矩阵

![Source evidence matrix](docs/assets/evidence-matrix.png)

| 能力 | 源码证据 | 边界 |
|---|---|---|
| BLAS/TLAS、RT pipeline、SBT 与光线发射 | [`src/renderer/RayTracer.cpp`](src/renderer/RayTracer.cpp) | 源码包含加速结构构建、shader group handles 和 `vkCmdTraceRaysKHR`；运行结果待实机验证 |
| 栅格回退渲染 | [`src/renderer/Rasterizer.cpp`](src/renderer/Rasterizer.cpp) | 源码包含 graphics pipeline 与 indexed draw；硬件回退行为待实机验证 |
| Temporal variance 与 A-trous 去噪 | [`src/denoise/Denoiser.cpp`](src/denoise/Denoiser.cpp) | 当前代码提供 history 资源及 variance clipping/A-trous 的 framework，完整 compute 执行仍未落地 |
| FSR 风格超分 | [`src/upscaler/FSR3Upscaler.cpp`](src/upscaler/FSR3Upscaler.cpp) | 自定义受启发原型源码模块，尚未完成 shader 编译验证且尚未接入主渲染循环；未集成官方 SDK，也不声明同等画质结果 |
| XeSS 风格超分 | [`src/upscaler/XeSSUpscaler.cpp`](src/upscaler/XeSSUpscaler.cpp) | 自定义受启发原型源码模块，尚未完成 shader 编译验证且尚未接入主渲染循环；未集成官方 SDK，也不声明同等画质结果 |
| GPU 计时 | [`src/debug/GpuTimer.h`](src/debug/GpuTimer.h) | 源码使用 `vkCmdWriteTimestamp` 和 query results；计时数据待实机采集 |
| PNG 截图 | [`src/debug/Screenshot.cpp`](src/debug/Screenshot.cpp) | 源码调用 `stbi_write_png`；截图只在 RT 分支可达，本作品集不提供运行时截图作为已验证结果 |

## 架构与工程决策

- `CMakeLists.txt` 固定 C++20，并通过 Vulkan、GLFW、GLM、nlohmann-json、Vulkan Memory Allocator、spdlog 与 ImGui 组织可执行目标。
- `vcpkg.json` 记录依赖清单，ImGui 启用 GLFW 与 Vulkan bindings。
- 光追扩展函数在 [`src/renderer/RayTracer.cpp`](src/renderer/RayTracer.cpp) 中通过 `vkGetDeviceProcAddr` 加载，使扩展调用位置集中且可追踪。
- 超分 integration boundary 位于应用主循环：项目内保留原型 shader、资源和 command recording 源码模块，[`src/app/Application.cpp`](src/app/Application.cpp) 当前未创建或调用这些模块。
- 自定义超分能力声明继续排除厂商 SDK 集成和厂商同等画质。
- 源码存在性与静态契约由验证脚本检查，运行正确性由 Windows 实机验收检查。

## 快速开始

前置条件：Windows 10/11、Vulkan SDK 1.3+、支持 Vulkan RT 的 GPU、CMake 3.25+、MSVC 2022 或兼容的 C++20 编译器，以及 Git。

推荐流程从仓库根目录执行：

```batch
git clone https://github.com/microsoft/vcpkg.git vcpkg
vcpkg\bootstrap-vcpkg.bat
vcpkg\vcpkg.exe install --triplet x64-windows
cmake -B build -S . ^
  -DCMAKE_TOOLCHAIN_FILE=vcpkg\scripts\buildsystems\vcpkg.cmake ^
  -DCMAKE_BUILD_TYPE=Release ^
  -DVULKAN_SDK=%VULKAN_SDK%
cmake --build build --config Release -j %NUMBER_OF_PROCESSORS%
build\Release\RoomRenderer.exe
```

`setup_vcpkg.bat` 是待 Windows 验证的旧辅助脚本。其 classic-mode 依赖列表遗漏 CMake 所需的 spdlog 和 manifest ImGui config；推荐依赖安装入口为上述仓库根目录下的 manifest 命令。以上命令是验收说明，执行结果仍需在目标 Windows 环境记录。

## Windows 实机验收

1. 安装 Vulkan SDK，并确认 `VULKAN_SDK` 指向目标 SDK。
2. 在仓库根目录克隆 vcpkg 到 `vcpkg`，再执行 `vcpkg\bootstrap-vcpkg.bat`。
3. 从仓库根目录执行 manifest 安装命令 `vcpkg\vcpkg.exe install --triplet x64-windows`，记录完整结果。
4. 按推荐流程执行 CMake configure 与 build，保存完整日志并确认生成 `build\Release\RoomRenderer.exe`。
5. 启动 `build\Release\RoomRenderer.exe`，在支持 Vulkan RT 的 GPU 上记录设备、驱动、分辨率和配置。
6. 验证当前主循环可达的光追路径、栅格路径与 GPU timestamp，并确认 RT output capture 仅在 RT 分支可达。
7. 完成 UpscalerFactory、资源绑定、command recording 和 shader 编译验证后，再验收自定义受启发原型源码模块。
8. 归档运行截图、兼容性结果和可复现 benchmark 后，再更新作品集声明。

## 验证

作品集静态契约使用以下命令验证：

```bash
cmake -P scripts/verify_portfolio.cmake
```

[![Gitee Go static verified](https://img.shields.io/badge/Gitee%20Go-static%20verified-brightgreen)](https://gitee.com/szzhoujiarui/RoomRenderer/gitee_go/pipelines/builds/86326/view)

该 Gitee Go 成功构建仅执行 CMake script-mode 静态验证，检查双语入口、章节、源码证据路径、PNG 引用及关键 Vulkan/PNG 调用；构建记录需登录 Gitee 后查看。静态验证不替代 Windows 构建或 GPU 运行验收。

## 实现边界

当前作品集不声明任何运行时截图、benchmark、兼容性结果或成功的 Windows 构建。PNG 路径指向仓库内的静态作品集图示，用于展示源码架构与证据分类，不属于运行时截图；运行产物仍需通过实机验收提供。

[`src/denoise/Denoiser.cpp`](src/denoise/Denoiser.cpp) 当前体现去噪资源与算法步骤 framework，不能作为完整 temporal variance/A-trous compute pipeline 已运行的证据。FSR/XeSS 路径属于自定义受启发原型源码模块，两个 temporal shader 当前存在 `historyColor` 同名遮蔽，尚未完成 shader 编译验证，也尚未接入主渲染循环；它们未集成官方 SDK，且不声明厂商同等画质结果。

## 项目结构

```text
RoomRenderer/
|-- README.md
|-- README.en.md
|-- CMakeLists.txt
|-- vcpkg.json
|-- scripts/verify_portfolio.cmake
|-- src/renderer/
|-- src/denoise/
|-- src/upscaler/
|-- src/debug/
|-- shaders/
|-- configs/
|-- build.bat
`-- setup_vcpkg.bat
```

## 许可证

MIT