# Wpyw DLSS — Minecraft Java 1.20.1 (Fabric)

在 Minecraft Java 版里接入 **NVIDIA DLSS 超分（Super Resolution）** 与 **帧生成（Frame Generation / 插帧）**。

> 工程名 `wpywdlss` / `MinecraftDLSS` 是**临时名**，随你改。

---

## 一、先讲清楚三个硬事实（省掉走弯路的成本）

### 1. DLSS 5 不是超分，也不是插帧

| | 超分 | 插帧 | 本质 |
|---|---|---|---|
| **DLSS 4** | ✅ Super Resolution | ✅ Multi Frame Generation（最高 6X） | 你要的就是这两个 |
| **DLSS 5** | ❌ | ❌ | **3D 引导神经渲染**：重建材质 / 光照 / 皮肤 / 阴影 / 反射 |

DLSS 5 于 2026-09-03 上线，**官方仅 RTX 50 系**，目前只有 NBA 2K27 一款游戏，集成走 **UE5 插件**路径。
在 **Streamline SDK 2.14.1 的 `include/` 与 `bin/x64/` 里不存在任何 dlssnr / 神经渲染的头文件或插件**——
即通用 Streamline 层根本没有 DLSS 5 的集成接口。

### 2. Minecraft Java 是 OpenGL，而 NGX 不支持 OpenGL

NGX / Streamline 只支持 **D3D11 / D3D12 / Vulkan**。所以 DLSS 进 MC Java 的唯一办法是：
游戏继续用 OpenGL 渲染，模组**内部再起一个 Vulkan 设备**，用外部内存/信号量把纹理零拷贝共享过去，
在 Vulkan 侧跑 NGX。

### 3. 真正的工程量在「运动矢量」

DLSS 超分必须吃 **运动矢量 + 深度 + 抖动投影矩阵**，而 Minecraft 的 OpenGL 管线**一个都不生产**。
这是本项目 80% 的工作量。在 **Iris + 光影包**环境下更难：Iris 接管整条管线、自己控制投影矩阵与 G-buffer，
且还有 Distant Horizons / Voxy 的 LOD 几何要算速度。

---

## 二、架构

```
┌─ Minecraft 1.20.1 (Java, OpenGL / LWJGL) ──────────────────────────┐
│  Fabric 模组 (本仓库 src/main/java)                                 │
│   • Mixin 投影矩阵亚像素抖动 (jitter)                               │
│   • Mixin 渲染分辨率 → 低分渲染 world framebuffer                   │
│   • 导出 depth / motion vector 纹理                                 │
│   • 在 present 点调用原生桥接                                        │
└────────────────────────┬──────────────────────────────────────────┘
                         │ JNI
┌────────────────────────▼──────────────────────────────────────────┐
│  自研原生桥接 DLL (C++ / MSVC)   ← native/  本项目核心               │
│   • 建 Vulkan 1.2+ 设备（同一块 GPU）                                │
│   • GL↔VK 外部内存互操作                                             │
│     GL_EXT_memory_object_win32 ↔ VK_KHR_external_memory_win32       │
│     GL_EXT_semaphore_win32      ↔ VK_KHR_external_semaphore_win32   │
│   • slInit / slSetVulkanDevice / slSetConstants                     │
│   • slDLSSSetOptions + slEvaluateFeature   （超分）                  │
│   • slDLSSGSetOptions                      （帧生成）                │
└────────────────────────┬──────────────────────────────────────────┘
                         │
             ┌───────────▼────────────┐
             │  sl.interposer.dll     │   ← 用户自备，不随模组分发
             │   ├─ sl.dlss.dll       │ → nvngx_dlss.dll   超分
             │   ├─ sl.dlss_g.dll     │ → nvngx_dlssg.dll  插帧
             │   └─ NvLowLatencyVk.dll│ → Reflex（Vulkan）
             └────────────────────────┘
```

---

## 三、NVIDIA 运行时：**绝不打包进模组**

`nvngx_dlss.dll` / `nvngx_dlssg.dll` / `sl.*.dll` 均为 NVIDIA 专有二进制，**不允许随模组再分发**。
本模组只提供**加载逻辑**，二进制由用户自行放置。

运行时查找顺序：

1. JVM 参数 `-Dwpywdlss.runtimeDir=<路径>`
2. `<gameDir>/ngx/`
3. `<gameDir>/config/ngx/`

需要的文件（全部来自 **Streamline SDK 2.14.1 的 `bin/x64/`**）：

| 文件 | 大小 | 用途 |
|---|---|---|
| `sl.interposer.dll` | 652,928 | Streamline 核心 |
| `sl.common.dll` | 843,392 | 公共层 |
| `sl.dlss.dll` | 422,016 | 超分插件 |
| `sl.dlss_g.dll` | 636,032 | 帧生成插件 |
| `nvngx_dlss.dll` | 58,956,912 | DLSS 超分模型 (310.9.1.0) |
| `nvngx_dlssg.dll` | 7,460,976 | DLSS 帧生成模型 (310.9.1.0) |
| `NvLowLatencyVk.dll` | 57,840 | Vulkan Reflex（可选） |

> 若 NGX 因缺少 `applicationId` 拒绝加载，可改用 `bin/x64/development/` 下的开发版 DLL 做实验。

---

## 四、构建

### Java 侧（Fabric 模组）

```powershell
$env:JAVA_HOME = 'C:\Program Files\Java\jdk-21.0.10'
.\gradlew.bat build
```

产物：`build/libs/wpywdlss-0.1.0.jar`

版本组合（对齐 Fabric 官方 1.20.1 分支）：
`minecraft 1.20.1` · `loader 0.19.5` · `loom 1.17-SNAPSHOT` · `fabric-api 0.92.12+1.20.1` · Mojang 官方映射

### 原生侧（C++ 桥接 DLL）

见 `native/`。使用 MSVC（VS2022 BuildTools 14.44.35207）+ CMake。

**不需要 Vulkan SDK**：Khronos 头文件取自 DLSS demo 自带的
`DLSS_Sample_App/donut/thirdparty/glfw/deps/vulkan/`，导入库由
`dumpbin /exports C:\Windows\System32\vulkan-1.dll` + `lib /def:` 自造。

---

## 五、路线图

| 阶段 | 目标 | 验证方式 |
|---|---|---|
| **P0 地基** | Fabric 工程可编译；原生桥接 DLL 可编译；JNI 打通；Vulkan 设备创建成功；GL↔VK 互操作往返 | 游戏内一张纹理经 GL→VK→GL 往返后画面一致 |
| **P1 数据源** | 深度纹理 + 抖动投影 + 运动矢量。**先在纯净版 / Sodium 下做** | 运动矢量可视化输出正确 |
| **P2 DLSS 超分** | 接 `sl.dlss`，出画面。applicationId 风险在此暴露 | 1080p→4K 提升且画质可接受 |
| **P3 HUD 原生分辨率** | 世界低分渲染、HUD/UI 保持原生清晰 | HUD 文字不糊 |
| **P4 帧生成** | 接 `sl.dlss_g`。最难一步（需接管 present 路径） | 输出帧率提升，伪影可接受 |
| **P5 Iris 兼容** | 在光影包环境下算运动矢量 | 主流光影包下不崩不糊 |

---

## 六、P0 实测结果（已跑通，非推演）

**环境**：RTX 5070 / 驱动 616.92 / Vulkan loader 1.4.341 / Win11 26100
**方式**：`tools/ProbeRunner.java` 独立加载桥接 DLL 调用 `nativeProbe()`，不启动游戏
**结论**：`nativeIsReady() = true`，exit code 0

| 检查项 | 实测结果 |
|---|---|
| Vulkan 实例 | ✅ `VK_SUCCESS`，loader 1.4.341 |
| 物理设备 | 2 个：**RTX 5070**（0x10de, DISCRETE, api 1.4.351）+ AMD 核显（0x1002, INTEGRATED, 1.4.315）；自动选中 NVIDIA |
| 设备扩展（291 可用） | ✅ `VK_KHR_external_memory_win32` / `VK_KHR_external_semaphore_win32` / `VK_KHR_timeline_semaphore` / `dedicated_allocation` / `image_format_list` / `synchronization2` 全部可用 |
| 设备创建 | ✅ `VK_SUCCESS`（queue family 0，已启用 timeline semaphore） |
| 互操作函数指针 | ✅ `vkGetMemoryWin32HandleKHR` / `vkGetSemaphoreWin32HandleKHR` / `vkImportSemaphoreWin32HandleKHR` 经 `vkGetDeviceProcAddr` 全部取到 |
| **镜像导出（go/no-go）** | ✅ **`OPAQUE_WIN32`: exportable=YES, importable=YES, dedicatedOnly=no** |
| 信号量 | ✅ `OPAQUE_WIN32`: exportable=YES, importable=YES |
| 显存 | 11,943 MiB device-local |

### 两个必须记住的实测细节

1. **`D3D12_HEAP` / `D3D11_TEXTURE` 只能导入、不能导出**（`exportable=no`）。
   这直接影响你那个 `rtx_vsr_host.dll`（只有 `NVSDK_NGX_D3D12_*` 接口）：
   它无法接收"OpenGL/Vulkan 分配、D3D12 导入"的纹理，**只能反过来由 D3D12 侧分配**再共享出来。
   所以 VSR 超分和 DLSS 超分**不能复用同一条互操作管线**，这是两套东西。
2. **`dedicatedOnly=no`**：不强制专用分配，意味着我们可以在同一块 VkDeviceMemory 里规划输入/输出镜像，省一次分配和一次拷贝。

### 常用命令

```powershell
# 编原生桥接（自动处理 vulkan-1.lib）
.\native\tools\build_native.cmd

# 只重造 vulkan-1.lib
.\native\tools\make_vulkan_lib.cmd

# 跑 P0 探测（不需要启动游戏）
$env:JAVA_HOME='C:\Program Files\Java\jdk-21.0.10'
java -cp "build\classes\java\main" `
     -Dwpywdlss.bridgePath=native\build\wpywdlss_bridge.dll `
     tools\ProbeRunner.java
```

---

## 七、OpenGL 互操作实测结果（2026-09-16，已跑通）

**为什么这一个探测决定所有路线的生死**：OpenGL **只能导入、不能导出**内存和信号量。
所以分配方必须是 Vulkan/D3D12，GL 只负责导入对方给过来的 Win32 HANDLE。
`GL_EXT_external_objects*` 是**导入 Vulkan 对象的另一条路**，走 `OPAQUE_WIN32` 时**不需要**它 ——
把它当必需项会得出假阴性（我第一版就写错了，已修正）。

`nativeProbeOpenGL()` 创建一个**隐藏 WGL 上下文**实测：

| 检查 | 结果 |
|---|---|
| GL_RENDERER | `NVIDIA GeForce RTX 5070/PCIe/SSE2` |
| GL_VERSION | `4.6.0 NVIDIA 616.92` |
| GL 扩展总数 | 405 |
| **`GL_EXT_memory_object`** | ✅ |
| **`GL_EXT_memory_object_win32`** | ✅ |
| **`GL_EXT_semaphore`** | ✅ |
| **`GL_EXT_semaphore_win32`** | ✅ |
| `glCreateMemoryObjectsEXT` | ✅ |
| **`glImportMemoryWin32HandleEXT`** | ✅ |
| **`glTextureStorageMem2DEXT`** | ✅ |
| **`glImportSemaphoreWin32HandleEXT`** | ✅ |
| `glDeleteMemoryObjectsEXT` / `glDeleteSemaphoresEXT` | ✅ |
| `GL_EXT_external_objects*` | ❌（**不需要**，走 OPAQUE_WIN32 时用不到）|
| `glCreateSemaphoresEXT` | ❌（**不需要**，GL 只导入不导出）|

**判定：`VERDICT: the OpenGL transport is AVAILABLE on this machine.`**

两侧合起来的完整链路（能力层面已验证）：

```
Vulkan/D3D12 分配镜像
      │ vkGetMemoryWin32HandleKHR / D3D12 CreateSharedHandle
      ▼  (Win32 HANDLE)
OpenGL  glCreateMemoryObjectsEXT → glImportMemoryWin32HandleEXT
        → glTextureStorageMem2DEXT   (得到可渲染/可采样的 GL 纹理)
      ▲  (Win32 信号量 HANDLE)
        glImportSemaphoreWin32HandleEXT
```

---

## 八、路线 C（ReShade 路线）落地清单

**先明确 C 在 OpenGL 下的天花板**（引自 DLSS5-Feeder 官方 Limitations）：

> **DLAA contract, optional reduced work extent on D3D11** — render resolution still equals DLAA output
> resolution... **D3D12, Vulkan and OpenGL paths remain at 100%.** This is not jittered DLSS Super
> Resolution, and **a Quality/Balanced/Performance mode cannot be added**.

即：**OpenGL 下是纯 DLAA + DLSS 5 神经渲染观感，内部渲染分辨率不降 → 零帧率收益，拿不到超分，也没有插帧。**
另外官方承认 **"the UI is processed with the scene"** —— Minecraft 的物品栏/聊天/F3 会被一起处理而拖影。

### 需要的组件

| 组件 | 来源 | 状态 |
|---|---|---|
| ReShade 6.8+（**需 add-on 支持**），装成 `opengl32.dll`，API 选 **OpenGL** | reshade.me | 需你下载 |
| **Generic Depth add-on** 启用并**认到 Minecraft 的场景深度** | ReShade 自带 | ⚠️ 最大风险点，见下 |
| 神经消费者：**Deep Fried Chicken**（推荐）或 Krish 的 `renodx-dlss5.addon64` | 各自 Discord | 需你获取（Discord 门禁，我拿不到）|
| `nvngx_dlssnr.dll` | 已有 | ✅ GUI-DLSS5 包里 |
| `nvngx_dlss.dll`（放在游戏目录旁） | 已有 | ✅ Streamline SDK 里 |
| 运动矢量提供者：**LumeniteFX Kernel（=3，推荐）** | github.com/umar-afzaal/LumeniteFX | 需下载 |
| `dlss5-feed.addon64` + `DLSS5_Feed.fx` | DLSS5-Feeder release | 需下载 |

### Minecraft 特有的四个坑（我预判，待实测确认）

1. **深度缓冲**：ReShade 的 Generic Depth 必须正确识别 Minecraft 的场景深度。
   Iris/光影会自建 FBO，Sodium 改了区块渲染 —— 识别很可能失败。
2. **GPU 选择**：这条路要求**渲染真的在 NVIDIA GPU 上**。你有 RTX 5070 + AMD 核显，
   必须在 Windows「设置 ▸ 显示 ▸ 图形」里把 Java 强制到 NVIDIA，否则 DLSS 无从谈起。
3. **HUD 拖影**：官方明说 UI 与场景一起处理。要么忍受，要么自己加 UI 遮罩。
4. **驱动版本**：他们实测的坏组合是驱动 **616.56 / 616.64**（`nvngx_dlssnr.dll` 内部 fault）。
   **你是 616.92，比他们测过的都新，未知。** 先跑他们的自检
   `host64\dlss5-feed-host64.exe --test`（`300/300 evaluates succeeded` 才算 OK）。

---

## 九、许可与合规

- 本模组代码：MIT
- **NVIDIA 专有二进制一律不再分发**，仅由用户自备（同 Salt's Anti-Aliasing 等既有项目的做法）
- 参考但不复制任何现有模组代码；`Super Resolution`（GPL-3.0）与 `Salt's Anti-Aliasing`（MIT）
  仅作为「这条路走得通」的存在性证据
- NGX `applicationId` 需向 NVIDIA 申请；在获批前 NVIDIA 目前为宽容放行（会打警告日志）