10分钟跑通OpenDLSS-NR：Windows编译构建与运行完整教程

OpenDLSS-NR 是一个基于 Vulkan 对 NVIDIA DLSS 5 Neural Rendering（神经渲染）网络的开源重实现，与原版逐比特精确一致。本文是一份面向新手的 Windows 编译构建与运行完整教程，带你从零克隆代码、搭建工具链，到跑通 demo 亲眼看到神经渲染开/关的画质差异。

一、先弄懂：OpenDLSS-NR 在做什么

上图来自项目自带的 WebGPU 端口（ports/browser-webgpu/）：左侧 NR OFF，右侧 NR ON，同一帧输入输出分辨率相同——它是"生成式神经渲染器"，不是超分器。

核心事实一览：

架构上仓库分四块，构建时各自独立：

• 主机层：src/（C++20），Vulkan 上下文、模型加载、网络图、dlss5vk命令行工具
• GLSL 内核：shaders/，cooperative-matrix FP8 GEMM 参考实现
• PTX 内核：scripts/ptx/，Python 生成器产出快速路径的 PTX
• 演示：demo/，把网络跑进 Filament 渲染框架内的真实场景

二、环境准备：Windows 编译前检查清单

开始之前，确认你的机器满足以下条件（详见 README.md 的 Requirements 一节）：

• 系统：Windows（demo 仅在 Windows 上构建验证过）
• GPU：NVIDIA Ada（RTX 40 系）或更新，驱动暴露VK_KHR_cooperative_matrix、VK_NV_cooperative_matrix2、VK_EXT_shader_float8、VK_NV_cuda_kernel_launch
• 工具：Visual Studio 2022+（C++ x64 工具集，Build Tools 亦可）、git、Python 3、Node.js + npm（仅场景转换需要）
• 无需安装 Vulkan SDK：工具链全部是便携式的，下载到本地tools/目录

💡 权重需要你自己提供：--model <目录>指向一个含manifest.json的模型目录。本仓库不包含权重与场景，这一点务必提前了解。

克隆仓库：

git clone https://gitcode.com/gh_mirrors/op/OpenDLSS-NR cd OpenDLSS-NR

三、10分钟构建：按顺序执行 5 条命令

所有命令都在仓库根目录、用 PowerShell 执行。前两步约 10 分钟可产出核心工具dlss5vk，后三步是可选的 Filament demo（其中 Filament 编译约 15 分钟）。

第 1 步：拉取便携工具链

scripts/fetch_tools.ps1 会下载 glslang、Vulkan-Headers、volk、CMake、Ninja 到tools/，重复执行会自动跳过已有项：

powershell -File scripts\fetch_tools.ps1

第 2 步：编译着色器与 PTX，构建核心工具

powershell -File scripts\build_shaders.ps1

scripts/build_shaders.ps1 用 glslang 把 shaders/ 下全部.comp编译为 SPIR-V，再用 Python 生成器产出全部 PTX 内核到build/ptx。构建完成后你会得到build/dlss5vk.exe。

第 3 步：获取并打补丁 Filament（demo 专属）

powershell -File scripts\fetch_filament.ps1

克隆 Filament v1.77.0 并应用 third_party/filament.patch——补丁新增了逐物体运动向量、Vulkan 互操作钩子和共享设备支持，这是网络能"插进"渲染帧的关键（详见 demo/README.md 的 The Filament patch 一节）。

第 4 步：编译 Filament（最耗时的一步）

powershell -File scripts\build_filament.ps1

产物在third_party/filament-install，约 15 分钟。可用环境变量DLSS5_BUILD_JOBS限制并行度（默认 8）。

第 5 步：构建 demo 可执行文件

powershell -File scripts\build_demo.ps1

scripts/build_demo.ps1 会编译 demo 着色器与 Filament 材质，再用 CMake + Ninja + MSVC 产出build/demo/dlss5-demo.exe。

四、运行：两种入口与操作按键

命令行工具：dlss5vk.exe

build\dlss5vk.exe bench --model <模型目录> --width 768 --height 768 build\dlss5vk.exe profile --model <模型目录> --width 768 --height 768

bench跑整网基准，profile输出每个 dispatch 的耗时。模型目录也可通过环境变量DLSS5VK_MODEL或默认的models\nr提供。

图形化 demo：dlss5-demo.exe

双击运行，或用辅助脚本 scripts/run_demo.ps1：

scripts\run_demo.ps1 -Model <模型目录> -Scene <场景.glb>

这是网络看到的输入：一帧已渲染画面（低动态范围代理）。按 N 键开启网络后，它会重新渲染这一帧——生成细节、调整色调与结构。

常用按键（demo/README.md）：

场景说明：build/scenes下每个含view.json的目录都会出现在Demo scene下拉框里。仓库不带场景，但 Filament 源码目录自带Fox.glb和AnimatedMorphCube.glb（无需转换），demo/views/ 已备好对应视图文件。

五、验证结果与常见问题

官方性能参考（RTX 4070 SUPER）

如果你的 RTX 40 系机器上 1080p 在 8ms 上下，说明构建成功。

常见问题排查

六、延伸阅读

构建跑通后，建议按 docs/README.md 的索引深入设计细节：

• docs/network.md —— 完整网络图：输入输出、分辨率金字塔、窗口阶段
• docs/numerics.md —— "bit-exact" 到底精确到什么程度
• docs/weights.md —— 模型目录与权重布局
• docs/execution.md —— Vulkan 调度与免 barrier 的 chaining
• docs/frame.md —— demo 的单帧流程：运动向量到时间复合