TruvisRenderer

TruvisRenderer 是一个基于 Rust、Vulkan 1.3 和 Slang 构建的实时渲染引擎与桌面编辑器，当前面向 Windows x64 与 NVIDIA RTX 平台。项目围绕实时路径追踪构建，涵盖 Vulkan RHI、RenderGraph、CPU/GPU 场景同步、异步资产加载和 Shader 工具链，通过分层架构与显式资源生命周期，将渲染算法、引擎基础设施和编辑器交互整合在一起。

引擎特色

• 分层架构与渲染运行时：采用 App → Renderer → Engine 的单向依赖，使用独立 RenderThread 和阶段化接口组织更新、场景准备、渲染与销毁；桌面编辑器和 standalone 应用共用完整的 TruvisRenderer。
• CPU/GPU 场景分离：GameWorld 持有 CPU 场景权威状态，RenderWorld 维护 GPU 派生表示；资产异步加载、实例变更同步与 GPU 资源延迟回收分别管理，明确区分 CPU 加载完成与 GPU 可见状态。
• Vulkan RHI 与 RenderGraph：封装 Vulkan 资源、管线和同步，支持 Bindless 与 Frames in Flight；RenderGraph 按显式 pass 顺序推导 image barrier、layout transition 和提交同步信息，并输出可检查的执行计划。
• 实时与离线路径追踪：统一采样 HDRI、自发光三角形与 analytic light，结合 NEE/MIS 完成多次反弹；实时路径支持 primary ReSTIR DI 时空复用与 SHARC world-space radiance cache，Offline 路径使用独立的采样序列和累计状态。
• DLSS 与显示处理：通过 NVIDIA Streamline 集成 DLSS Super Resolution、DLAA 与 Ray Reconstruction，维护 depth、motion vector 和材质输入；支持自动曝光、Color Grading、AgX 与 Khronos PBR Neutral 色调映射。
• 原生视口与场景编辑：Tauri + React 编辑器嵌入原生 Vulkan viewport，支持对象筛选与拾取、选中描边、平移 Gizmo，以及材质、灯光和 HDRI 环境编辑。
• Shader 与资产工具链：提供 Slang 编译、共享 Shader ABI 与 Rust binding 生成工具链，通过 C ABI 集成 Rust/C++ 模块；.gltf / .glb 使用 Rust loader，其他模型格式通过 Assimp 导入。

特性展示

四个视图按左上、右上、左下、右下依次展示 Realtime + DLAA 基线、ReSTIR DI + SHARC、进一步叠加 DLSS Ray Reconstruction，以及 Offline 累计结果。各视图使用相同场景与相机，便于观察不同渲染路径和功能组合的差异。

快速开始

环境要求

• Windows x64
• 支持 Vulkan Ray Tracing 与 DLSS 的 NVIDIA RTX GPU，以及匹配的显卡驱动
• Rust 1.85+（workspace 使用 Rust 2024 edition）
• Vulkan SDK 1.3+
• Node.js 20.19.x 或 22.12+，以及 npm
• CMake 3.21+；Visual Studio 2026 generator 需要 PATH 中的 CMake 4.2+
• Visual Studio 2022 或 2026，并安装 MSVC C++ workload
• LLVM LLD，并确保 lld-link.exe 位于 PATH；Cargo 的 Windows MSVC target 使用它缩短链接时间
• 已配置 VCPKG_ROOT
• just 与 Nushell

获取资源并运行

just fetch-res
just truvis

just fetch-res 下载项目运行所需的资产与外部工具。just truvis 会依次构建 Web editor、shader、Debug CXX 绑定和主体应用，因此首次运行耗时会更长。

resources.toml 中的资源默认都会参与下载；标记 download_by_default = false 的按需资源需要显式指定名称：

just fetch-res sponza-1
just fetch-res --all

显式指定资源时只处理指定项；--all 会处理包括按需资源在内的全部配置项。

场景转换可运行 just scene-export <scene.blend 或 scene.fbx> <输出目录>；脚本只导出 glTF 与外部贴图，场景中的相机和灯光随 glTF 一起保存。转换完成后可用 python scripts/scene/validate_gltf.py --scene <输出目录>/scene.gltf 校验资源引用。

构建完整 workspace 时只需执行：

just build-all

build-all 已包含 Web editor、shader 和 Debug / Release CXX 构建，无需预先重复执行这些步骤。

根目录的 cxx/ 是完整且独立的 native CMake project，包含 CMakeLists.txt、 CMakePresets.json、vcpkg.json、全部 C++ modules、构建工具和 Rust binding。日常仍推荐通过 just cxx 完成 CMake build、binding 生成和 runtime 部署。

其他运行入口

just triangle
just cornell
just shader-toy
just truvis-direct

truvis-direct 仍会构建 Web editor，但不会重新生成 shader 或 CXX 绑定，适合确认这些产物已经是最新状态时使用。

所有渲染入口默认开启 Vulkan validation layer，可追加 no-validation 关闭。Truvis 和 Cornell 入口还可追加 imgui，启用 Streamline ImGui 调试界面：

just truvis imgui
just truvis no-validation
just truvis imgui no-validation

Truvis 与 Cornell 都默认启动 Manual 手工材质测试场景，均可选择 Sponza 或 Cornell Box。Cornell 入口使用完整 TruvisRenderer，提供不带 Tauri/Web Editor 的 standalone 窗口：

just truvis --scene manual
just truvis --scene sponza
just truvis --scene cornell
just cornell --scene cornell
just cornell imgui --scene sponza
cargo run --bin rt-cornell -- --scene manual
cargo run --bin truvis-app -- --scene sponza

基本操作

操作	输入
前后、左右移动	W / S、A / D
垂直移动	E / Q
自由观察	按住鼠标右键拖动
围绕鼠标命中位置观察	按住鼠标中键拖动
沿命中表面平移	Shift + 鼠标中键拖动
朝鼠标位置缩放	滚动鼠标滚轮
选择场景对象	鼠标左键点击 viewport

架构速览

flowchart LR
    App["App<br/>Tauri Editor / Standalone Samples"] --> Renderer["Renderer<br/>TruvisRenderer / Pass / Shader"]
    Renderer --> Engine["Engine<br/>World / Assets · RenderRuntime<br/>RenderGraph · Vulkan RHI<br/>RenderLoop / RenderThread · Platform"]
    App -->|窗口与线程宿主| Engine

图中箭头表示层间依赖。App 负责应用启动、编辑器集成与窗口宿主组装；Renderer 负责具体渲染算法、交互和 pass 编排；Engine 提供场景与资产、渲染运行时、RenderGraph、Vulkan RHI 和平台基础设施。

CPU 场景由 GameWorld 权威持有，RenderRuntime 在 prepare 阶段同步到 GPU RenderWorld，渲染 pass 通过只读场景视图使用准备后的数据。详细的依赖方向、线程边界和资源契约请阅读 docs/ARCHITECTURE.md。

坐标系约定

项目使用右手坐标系，Y 轴向上，默认相机朝向 -Z。光栅化阶段使用负 viewport height，保持 Vulkan clip space 到左上角为原点的 framebuffer 坐标映射一致。

当前支持范围

• 当前以 Windows x64、NVIDIA RTX 和源码构建为主要开发目标，仓库不提供预编译安装包。
• .gltf / .glb 当前支持 material、mesh 与 instance 导入；外部 image URI 可以作为纹理路径，GLB / data URI 内嵌贴图尚未接入现有纹理身份模型。
• ReSTIR DI 当前服务 primary direct lighting；secondary bounce 继续使用统一 NEE。
• Offline 路径拥有独立累计状态，不复用 DLSS、ReSTIR DI、SHARC 或 realtime temporal state。

文档导航

• just 命令、选项与依赖图
• 架构入口
• Editor 子系统边界与一致性
• CPU Scene 到 GPU Scene 同步机制
• RenderGraph 与帧内数据流
• Realtime RT 采样流程
• RenderRuntime 阶段说明
• RenderRuntime 对象层级
• 点选流程
• 应用壳模块说明
• 主体 Truvis Renderer
• Shader 模块说明
• CXX 工具链与 native project