Files
airdef/docs/DLSS-TESTING.md
T
chexit 3a992e7369
build / mod (push) Failing after 31s
Point horizon at the DLSS temporal-stability fix; document the RTX checks
Engine agent/dlss-temporal-stability (a791e8439 -> acfb379aa):
- f536fa958 DLSS: declare the jittered motion vectors (MVJittered). The create flags left
  MVJittered unset, so NGX applied the jitter offset on top of the already-jittered motion
  buffer — the camera jitter counted twice, the severe shaking. Contract verified against the
  DLSS Programming Guide (31 March 2026) §3.6.1-3.6.3/§3.7.3/§3.8.1, nvsdk_ngx_defs.h and
  Streamline's dlssEntry.cpp (pixel-space vectors take MV.Scale 1.0; the {1/w,1/h} advice is
  Streamline's own constant, scaled back by its plugin).
- 26ee82398 Native TAA: a reactive mask for water (its own depth, binding 7; less history where
  the waves/glint animate fastest, faded to 96 blocks) + the wind-motion contract test.
- acfb379aa Wind-blown leaves and plants carry their own motion vectors (previous frame's wind
  time/strength in Globals.hd_motion.zw, terrain.wgsl wind_offset_at).

Verified on Mac (no RTX): horizon-client --lib 1242 passed / 0 failed; taau_gpu_smoke on Metal
(fixed decode at the spatial filter's error floor, phase spread 0.0029 vs legacy 0.0156); naga
validation + HLSL translation of every HD shader and terrain/entity; frame/global layouts;
deterministic jitter/reprojection fixtures; non-dlss binary build; clippy clean on the touched
files. NGX evaluation itself awaits RTX — docs/DLSS-TESTING.md has the verification steps and
three fallback variants (jitter sign/axes, Streamline-style scale, non-jittered conversion pass).

Co-Authored-By: Kimi Code <noreply@moonshot.ai>
2026-11-21 16:56:38 +03:00

156 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Проверка DLSS SR на Windows / RTX
Это тестовая, а не релизная сборка #124. Она включает native DLSS Super Resolution через Vulkan и сохраняет обычный TAAU как fallback. Frame generation здесь нет; RTX 3060 его и не поддерживает.
## Temporal stability: дрожь с DLSS и мерцание native TAAU (ветка agent/dlss-temporal-stability)
### Что исправлено
**DLSS (сильная дрожь всего изображения).** Буфер motion в G-buffer — это current→previous в *джиттеренных* пикселях рендера (оба кадра со своим джиттером). Флаги создания DLSS-контекста не включали `MVJittered`, поэтому NGX использовал векторы как есть **и** применял переданный `jitter_offset` — джиттер камеры учитывался дважды, отсюда «дрожит адски». Исправление: флаг `DlssFeatureFlags::JitteredMotionVectors` (`horizon/crates/horizon-client/src/gfx/hd/dlss.rs`, коммит f536fa958). С ним NGX сам вычитает разницу джиттеров из векторов по per-frame `jitter_offset`.
Контракт сверен по первоисточникам (не по догадкам):
- **NVIDIA DLSS Programming Guide** (редакция 31 марта 2026, SDK 310.x — тот же, что оборачивает `dlss_wgpu` 6.0.0), `doc/DLSS_Programming_Guide_Release.pdf` из [NVIDIA/DLSS](https://github.com/NVIDIA/DLSS):
- §3.6/3.6.1: векторы — current→previous, **в пикселях render-разрешения**, начало координат сверху слева, y вниз; формат RG16F/RG32F. Наш буфер (`Rg16Float`, `terrain.wgsl`/`entity.wgsl` `motion_pixels`) ровно такой.
- §3.6.2: `MVJittered=1` — «DLSS then internally subtracts jitter from the motion vectors using the jitter offset values provided during the Evaluate call»; `MVLowRes=1` — векторы в render-разрешении (NGX сам их dilate'ит). Оба флага теперь стоят.
- §3.6.3: `InMVScaleX/Y = 1.0`, если масштабирование не нужно. Пиксельные векторы не масштабируются — `motion_vector_scale: [1,1]` оставлен. **Важно:** совет `{1/renderWidth, 1/renderHeight}` из гайда Streamline относится к константе `sl::Constants::mvecScale` самого Streamline: его плагин (`source/plugins/sl.dlss/dlssEntry.cpp`) умножает её обратно на renderWidth и передаёт в NGX `MV.Scale = 1.0` для pixel-space (`mvecPixelSpace ? 1.0f : mvecScale.x * renderWidth`). `dlss_wgpu` зовёт NGX напрямую, без Streamline, поэтому у нас 1.0.
- §3.7.3: `jitter_offset` — джиттер текущего кадра **в пикселях render-таргета**, в той же системе координат, что векторы (y вниз), в пределах ±0.5. `scene.jitter_px` именно такой.
- §3.8.1: `DepthInverted=1` для reversed-Z — уже стоял.
- Заголовок NGX `include/nvsdk_ngx_defs.h` (NVIDIA/DLSS): флаг `NVSDK_NGX_DLSS_Feature_Flags_MVJittered = 1 << 2`.
- Исходник Streamline `dlssEntry.cpp`: `motionVectorsJittered == eTrue → MVJittered`, jitter передаётся как есть.
**Native TAAU (слабое мерцание, особенно на воде).** Две причины найдены и исправлены (коммиты 26ee82398, acfb379aa):
1. **Вода анимируется без геометрического движения**: волны наклоняют нормали, преломление/SSR-отражение/блики меняются каждый кадр, а motion-буфер на пикселях воды несёт движение только дна. История TAA конфликтовала с кадром — мерцание. Теперь TAA-проход читает собственную глубину воды (binding 7) и снижает вес истории там, где вода анимируется быстрее всего — вблизи камеры (до 0.8 для `fs_taa`, до 0.7 для `fs_taau`, спад до 96 блоков; дальняя вода с медленными волнами сохраняет полный вес). Это reactive mask; качество не снижается, TAA не выключается.
2. **Листва и растения качаются на ветру**, но motion-буфер знал только камеру (`prev_clip` строился из текущей wind-позиции). Теперь предыдущая позиция вершины вычисляется с ветром *прошлого* кадра (`Globals.hd_motion.zw` = прошлые секунды/сила ветра, `terrain.wgsl` `wind_offset_at`) — листва несёт собственное движение, мерцание кроны и дальней лесополосы уходит.
Тени: каскады уже привязаны к текселям в мировых координатах (`hd::cascades`, f64 snap) — crawl отсутствует; дальняя каскада перерисовывается через кадр (`HORIZON_HD_SHADOW_FAST`), её матрица между перерисовками сдвигается за камерой — это корректно. Точность motion на дальних дистанциях достаточная: f16 хранит субпиксельные значения точно, f32-разница clip-координат на 500 блоках даёт ошибку ~1e-4 px.
### Что проверить на RTX (порядок)
1. Собрать с DLSS: `py tools\airdef.py all` (ветка `agent/dlss-temporal-stability`), запустить `test-dlss.bat --world "Имя мира"`. В `%APPDATA%\horizon\logs\latest.log` должна быть строка `DLSS Super Resolution: [1706, 960] -> [2560, 1440]` (для 1440p при масштабе 2/3) и не должно быть `using native TAAU` / `DLSS evaluation failed`.
2. **Статичная сцена — главный тест.** Встать неподвижно, смотреть на дальние статичные объекты (горы, строения) 10–15 секунд. Изображение не должно дрожать/вибрировать. Затем медленно повернуть камеру — не должно быть smear/ghosting на статичном мире. Для увеличения используй встроенный Windows Screen Magnifier (Win+«+», отключить «Smooth edges of images and text») — гайд §8.4.1.
3. **Движение**: `/airdef move 2` или `/airdef wave shahed 8 300` — движущиеся модели не должны двоиться/размазываться; дым и вспышки смотреть отдельно.
4. **Вода и листва, DLSS off** (`dlss off` через меню мода или контрольный сокет, без перезапуска): постоять у воды с ветром — мерцание/«вибрация» воды и кроны должны заметно уменьшиться против старой сборки. Блики на воде остаются живыми (это анимация, не артефакт).
5. **Motion-визуализация** (отдельный прогон, не для замера качества): `HORIZON_HD_DEBUG_MOTION=1` — на статичной сцене векторы должны быть почти нулевыми (субпиксельная разница джиттеров), без крупных пятен. Это проверяет буфер, который видит NGX.
6. Скриншоты одного ракурса: DLSS on / DLSS off, статика и движение; лог обоих прогонов.
Опционально (для глубокой отладки джиттера): dev-версия `nvngx_dlss.dll` (фича `debug_overlay` у `dlss_wgpu` + `DLSS_SDK` с dev-профилем) даёт оверлей §8.2 и jitter-отладку §8.4: offsets всегда внутри ±0.5, хоткеи CTRL+ALT+F9/F10 меняют знак/оси джиттера на лету.
### Если дрожь осталась: варианты по порядку (быстрая итерация)
Все правки — в `horizon/crates/horizon-client/src/gfx/hd/dlss.rs` (движок, ветка `agent/dlss-temporal-stability`), пересборка только игры.
- **Вариант A (проверка знака/осей джиттера).** В `render()` передавать `jitter_offset: [jitter[0], -jitter[1]]` (или `[-jitter[0], jitter[1]]`, или поменять оси местами). По документации наша система координат совпадает с NGX, так что это маловероятно, но гайд §8.4.1 советует именно это при остаточной дрожи. Признак: дрожь уменьшается при одном из знаков/осей.
- **Вариант B (нормализация Streamline).** `motion_vector_scale: Some([1.0 / self.world[0] as f32, 1.0 / self.world[1] as f32])`. Противоречит §3.6.3 для сырого NGX (и исходнику Streamline), но дёшево проверяется. Признак: если дрожь была от масштаба, картинка сразу стабилизируется; если станет хуже/размазаннее — вернуть `[1,1]`.
- **Вариант C (неджиттеренный буфер вместо флага).** Убрать `JitteredMotionVectors` из `FEATURE_FLAGS` и добавить конверсионный проход перед NGX: новый `Rg16Float`-таргет world-размера, fullscreen-шейдер пишет `motion.xy + frame.taa_params.zw - frame.prev_jitter.xy` (в точности коррекция `fs_taau`, taa.wgsl:234), в `DlssSuperResolutionRenderParameters.motion_vectors` подать его. Это зеркальный путь: NGX получает векторы без джиттера и использует их напрямую (§3.6.2, флаг=0). Признак: если флаг MVJittered в драйверной версии NGX работает иначе, чем описано, этот путь стабилизирует картинку.
Если дрожь ушла, но **только вода/анимированные материалы** двоится под DLSS — это отдельная задача: у NGX есть входы transparency/responsivity mask, `dlss_wgpu` передаёт их пустыми; native-путь теперь имеет reactive mask для воды.
### Что проверено на Mac, а что ждёт RTX
Проверено (macOS, Metal, без DLSS-устройства): вся сюита `cargo test -p horizon-client --lib` — 1242 passed / 0 failed; GPU A/B smoke `taau_gpu_smoke_still_surface_ab` (Apple M5): исправленный decode даёт ошибку 0.0048 на уровне собственного пространственного фильтра (0.00478) и разброс по фазам 0.0029 против 0.0156 у старого decode; shader-валидация naga + трансляция HLSL для всех HD-шейдеров и terrain/entity; раскладка `HdFrame`/`Globals`; детерминизм джиттера и репроекции (численные тесты на всех фазах Halton); сборка бинарника без фичи `dlss`. Сам `dlss.rs` на Mac не компилируется (cfg windows/linux + feature) — флаг и тест `the_feature_flags_match_the_motion_contract` проверятся на Windows-сборке.
Ждёт RTX: собственно NGX-оценка (стабильность статики, движение, вода), тест флага в `cargo test -p horizon-client --features dlss --lib gfx::hd::dlss`, визуальное сравнение воды/листвы с reactive mask и wind-motion.
## Переключатель DLSS
В сборках с фичей `dlss` DLSS теперь включён по умолчанию, а не только через `HORIZON_DLSS=1`:
- Меню мода: **N → Огонь, ремонт, эффекты… → DLSS (NVIDIA)**. Строка показывает состояние; на устройстве без DLSS переключение — мягкий no-op («недоступен»), запрос сохраняется и применяется при следующем запуске, если устройство его поддерживает.
- Команда контрольного сокета: `dlss on|off|status` (`available` — открыт ли DLSS-девайс, `dlss` — запрос игрока).
- Настройка `dlss:true|false` в `horizon-graphics.txt`; `HORIZON_DLSS=1|0` по-прежнему переопределяет её при старте.
Выключение переходит на native TAAU со следующего кадра: разделённые истории #137 делают переход чистым в обе стороны (NGX сбрасывается при возобновлении, первый native кадр не читает устаревшую историю). Включение после старта с выключенным DLSS применяется при следующем запуске — девайс открывается под DLSS только при старте. Разрешение рендера остаётся выбором игрока в настройках Horizon: масштаб 2/3 по умолчанию действует, только когда DLSS включён и реально доступен.
Для A/B ниже `test-dlss.bat`/`test-native.bat` работают как раньше; если старт был с DLSS, оба режима можно снять и одним прогоном через `dlss off`/`dlss on` без перезапуска.
## Быстрый старт
1. Один раз запусти обычный Horizon Launcher, чтобы он подготовил ресурсы Minecraft 26.3.
2. Распакуй `airdef-dlss-windows-x86_64.zip`. Не удаляй `nvngx_dlss.dll`: он должен остаться рядом с `horizon-client.exe`. Если Windows сообщает об отсутствии `MSVCP140.dll` или `VCRUNTIME140.dll`, поставь Microsoft Visual C++ Redistributable 2015–2022 x64.
3. Запусти **`test-dlss.bat --world "Имя мира"**. Скрипт сам включит мод, `HORIZON_DLSS=1` и GPU pass timing.
4. В игре выполни одну и ту же последовательность:
```text
/airdef shader hd
/airdef deploy radar_track
/airdef deploy s400
/airdef damage off
/airdef wave shahed 8 300
```
Подожди около 20 секунд, пока начнётся налёт. Для движущихся моделей подойдёт и `/airdef move 2`.
5. Посмотри на ракеты/технику, сделай скриншот и запиши FPS/кадр. Не включай `HORIZON_HD_DEBUG_MOTION` при измерении качества или FPS.
6. Выйди и запусти **`test-native.bat --world "Имя мира"`**. Он использует TAAU с тем же масштабом 2/3 и тем же GPU timing. Повтори ту же сцену, ракурс и скриншоты.
Для честного A/B используй один мир и одну позицию камеры. Если налёт уже закончился, запусти следующий `/airdef wave shahed 8 300`. Не меняй разрешение окна или HD-настройки между прогонами.
## Что подтверждает, что DLSS действительно включён
В `%APPDATA%\horizon\logs\latest.log` должна быть строка вроде:
```text
DLSS Super Resolution: [1280, 720] -> [1920, 1080]
```
Не должно быть `using native TAAU`, `FeatureNotSupported`, `no DLSS context` или `DLSS evaluation failed`. Само наличие повышенного FPS не считается подтверждением backend.
Скрипты включают `HORIZON_SHADER_PACK_TIMING=1`, поэтому в лог попадают GPU pass timings. Сравнивай не только средний FPS, но и микрофризы, дым, вспышки и движущиеся ракеты.
## Что прислать
- `%APPDATA%\horizon\logs\latest.log` после DLSS-прогона.
- Скриншоты одного ракурса с DLSS и native TAAU, желательно с движущейся техникой/ракетой и отдельно с дымом.
- Скриншот FPS/debug overlay обоих режимов или текстовые значения FPS.
- Если есть артефакты: кратко, что именно не так и меняется ли оно при движении камеры.
- Сохранения миров присылать не нужно.
## Если игра не запускается
- Сначала проверь, что `nvngx_dlss.dll` лежит рядом с `horizon-client.exe` и ресурсы подготовлены лаунчером.
- При ошибке про Vulkan/NGX пришли `latest.log`: там должна быть конкретная причина. Не подменяй её догадкой про драйвер.
- При `FeatureNotSupported` или другом сбое игра должна продолжить работу через native TAAU; это будет видно в логе. Такой запуск не является успешным тестом DLSS.
- `test-native.bat` нужен только для сравнения; он не включает DLSS.
## Сборка самостоятельно вместо готового архива
Нужны только Rust (с `x86_64-pc-windows-msvc` и `wasm32-unknown-unknown`) и Visual Studio Build Tools с C++. Ветка — `kimi-work`.
NVIDIA DLSS SDK, Vulkan SDK и LLVM ставить вручную больше не нужно: на Windows с NVIDIA RTX `airdef.py` сам скачивает всё, что читает `dlss_wgpu` при сборке (включая `libclang.dll` для bindgen), и кладёт `nvngx_dlss.dll` рядом с `horizon-client.exe`.
```powershell
git clone --branch kimi-work https://gitea.maoniao.team/chexit/airdef.git
cd airdef
rustup target add x86_64-pc-windows-msvc wasm32-unknown-unknown
py tools\airdef.py all
```
`all` делает `fork`, `game`, `mod`, `install`. На Windows + RTX шаг `game`:
1. Определяет новейший стабильный тег `v310.9.x` в [NVIDIA/DLSS](https://github.com/NVIDIA/DLSS) через GitHub API; при недоступности API берёт закреплённый `v310.9.1`.
2. Скачивает выборочно (не весь репозиторий): `include/*.h`, `lib/Windows_x86_64/x64/nvsdk_ngx_d.lib` и `nvsdk_ngx_s.lib`, `lib/Windows_x86_64/rel/nvngx_dlss.dll` (~59 МБ). Итог — около 67 МБ один раз.
3. Скачивает только заголовки [KhronosGroup/Vulkan-Headers](https://github.com/KhronosGroup/Vulkan-Headers) в `Include/`: полный LunarG SDK не нужен, `build.rs` линкует Vulkan сам.
4. Ищет уже установленный `libclang.dll` (`LIBCLANG_PATH`, `PATH`, `C:\Program Files\LLVM\bin`, LLVM из Visual Studio). Если его нет — скачивает NuGet-пакет [`libclang.runtime.win-x64`](https://www.nuget.org/packages/libclang.runtime.win-x64) (~34 МБ) и распаковывает из него только `runtimes/win-x64/native/libclang.dll`.
5. Собирает с `--features mods,dlss`, передавая `DLSS_SDK`, `VULKAN_SDK` и `LIBCLANG_PATH` в окружение cargo, затем копирует свежий `nvngx_dlss.dll` рядом с собранным `horizon-client.exe`.
Кэш и повторные сборки:
```text
.horizon-cache/dlss-sdk/<tag>/ include/ + lib/Windows_x86_64/{x64,rel} + airdef-install.json
.horizon-cache/vulkan-headers/<tag>/ Include/vulkan/ + Include/vk_video/ + airdef-install.json
.horizon-cache/libclang/<version>/ libclang.dll + airdef-install.json
```
Повторный запуск видит маркер и полный набор файлов и ничего не скачивает. Удалить кэш можно целиком — при следующей сборке он появится снова.
Ручное переопределение по-прежнему работает и имеет приоритет: если задать `DLSS_SDK` (корень с `include/nvsdk_ngx*.h` и `lib/Windows_x86_64/x64/`), `VULKAN_SDK` (с `Include/vulkan/vulkan.h`) и/или `LIBCLANG_PATH` (каталог с `libclang.dll`), автоскачивание для этого компонента не выполняется. Если явный путь неполный, `airdef.py` предупреждает и собирает `mods`; чтобы вернуть автоскачивание, убери переменную.
Ручная альтернатива для libclang: `winget install LLVM.LLVM`, затем задать `LIBCLANG_PATH` на каталог `bin` установленного LLVM (там лежит `libclang.dll`).
При любой сетевой ошибке, недоступном GitHub/nuget.org, неполном скачивании или если libclang так и не нашёлся, сборка не падает: печатается предупреждение, ставится `--features mods`, и игра остаётся на native TAAU. На macOS и Linux, а также на Windows без RTX, автоскачивания нет — сразу `mods`.
Если bindgen всё же пишет `Unable to find libclang`, проверь `LIBCLANG_PATH`: он должен указывать на каталог, в котором лежит `libclang.dll` (не на сам файл). Удобно один раз выполнить `winget install LLVM.LLVM` и указать `C:\Program Files\LLVM\bin`.
Если `nvngx_dlss.dll` нужен отдельно (например, для ручной раскладки), он лежит в кэше: `.horizon-cache/dlss-sdk/<tag>/lib/Windows_x86_64/rel/nvngx_dlss.dll`. Его версия совпадает с самым новым тегом, который нашёл `airdef.py`.