feat: hardware quality presets with safe dynamic VRAM budget clamp #398

Merged

oscarlosu-lab merged 1 commit from feat/hardware-quality-presets into main

2026-11-08 00:03:07 +00:00

oscarlosu-lab commented

2026-11-07 23:37:19 +00:00

(Migrated from github.com)

Summary of Changes

As suggested in #372, this pull request introduces a standalone, dedicated hardware quality preset system in the in-game F1 / Insert menu (vk_menu.cpp), tailored to different hardware tiers with dynamic texture cache budget tuning in gpu/vk/vk_texture.cpp.

1. 6-Tier Quality Preset Selector

Minimum (4GB): 50% scale, Lanczos upscaler (50% sharpness), FrameGen 2x, Handheld profile ON, 2.2 GB texture budget.
Low (6GB): 75% scale, Lanczos upscaler (35% sharpness), FrameGen 2x, Handheld profile ON, 3.6 GB texture budget.
Balanced (8GB): 100% scale, Catmull-Rom upscaler (25% sharpness), FrameGen 2x, Handheld profile OFF, 4.8 GB texture budget.
High (12GB): 100% scale, Lanczos upscaler (30% sharpness), FrameGen 2x, Handheld profile OFF, 7.5 GB texture budget.
Ultra (16GB+): 100% scale, Lanczos upscaler (40% sharpness), FrameGen 3x, Handheld profile OFF, 11 GB texture budget.
Custom: Default transparent mode preserved whenever the player tweaks any individual graphic setting.

2. Safe Dynamic VRAM Clamping (Prevents VK_ERROR_DEVICE_LOST)

To address the concern raised in #372 regarding texture budgets on 8-12 GB GPUs:

gpu/vk/vk_texture.cpp now implements an automatic safety clamp:
budget = std::min(budget, (allowed / 4) * 3);
Even if an 8 GB or 12 GB card selects High or Ultra, the requested texture budget is automatically capped to at most 75% of the driver-reported available memory (allowed), guaranteeing that the game will never over-commit VRAM or trigger a VK_ERROR_DEVICE_LOST crash.
On cards with 16 GB+ VRAM, the full 11 GB cache budget is used without unnecessary evictions.

3. Zero Regression & Persistence

Saved seamlessly in hookshot_options.ini as quality_preset=<0..5>.
If preset == 0 (Custom/Default), texture eviction behavior is 1:1 bit-for-bit identical to upstream (own).

🧪 Verification Report

Unit & Regression Tests:
- nx2/test_nup_paths.py: 21 tests OK
- tests/test_make_game_cache.py: 6 tests OK
- tests/test_failure_reason.py: 6 tests OK
- tests/test_dispatch_clock.py: PASS
- tests/test_desc_clock.py: PASS
- nx2/test_version.py: OK
Tested GPU: NVIDIA GeForce RTX 3060 (12 GB VRAM) on Windows 11 Pro 64-bit.
In-Game Testing:
- Cycled between Minimum, Low, Balanced, High, and Ultra across Kokiri Forest, Hyrule Field, and Castle Town.
- Confirmed proper texture retention without micro-stutters or texture streaming hitches.
- Verified that manual alteration of resolution or upscaler instantly disengages the preset and switches label to Custom.

### Summary of Changes As suggested in #372, this pull request introduces a standalone, dedicated hardware quality preset system in the in-game <kbd>F1</kbd> / <kbd>Insert</kbd> menu (vk_menu.cpp), tailored to different hardware tiers with dynamic texture cache budget tuning in gpu/vk/vk_texture.cpp. #### 1. 6-Tier Quality Preset Selector * Minimum (4GB): 50% scale, Lanczos upscaler (50% sharpness), FrameGen 2x, Handheld profile ON, 2.2 GB texture budget. * Low (6GB): 75% scale, Lanczos upscaler (35% sharpness), FrameGen 2x, Handheld profile ON, 3.6 GB texture budget. * Balanced (8GB): 100% scale, Catmull-Rom upscaler (25% sharpness), FrameGen 2x, Handheld profile OFF, 4.8 GB texture budget. * High (12GB): 100% scale, Lanczos upscaler (30% sharpness), FrameGen 2x, Handheld profile OFF, 7.5 GB texture budget. * Ultra (16GB+): 100% scale, Lanczos upscaler (40% sharpness), FrameGen 3x, Handheld profile OFF, 11 GB texture budget. * Custom: Default transparent mode preserved whenever the player tweaks any individual graphic setting. #### 2. Safe Dynamic VRAM Clamping (Prevents VK_ERROR_DEVICE_LOST) To address the concern raised in #372 regarding texture budgets on 8-12 GB GPUs: * gpu/vk/vk_texture.cpp now implements an automatic safety clamp: budget = std::min(budget, (allowed / 4) * 3); * Even if an 8 GB or 12 GB card selects High or Ultra, the requested texture budget is automatically capped to at most **75% of the driver-reported available memory** (allowed), guaranteeing that the game will never over-commit VRAM or trigger a VK_ERROR_DEVICE_LOST crash. * On cards with 16 GB+ VRAM, the full 11 GB cache budget is used without unnecessary evictions. #### 3. Zero Regression & Persistence * Saved seamlessly in hookshot_options.ini as quality_preset=<0..5>. * If preset == 0 (Custom/Default), texture eviction behavior is 1:1 bit-for-bit identical to upstream (own). --- ### 🧪 Verification Report * **Unit & Regression Tests**: * nx2/test_nup_paths.py: 21 tests OK * tests/test_make_game_cache.py: 6 tests OK * tests/test_failure_reason.py: 6 tests OK * tests/test_dispatch_clock.py: PASS * tests/test_desc_clock.py: PASS * nx2/test_version.py: OK * **Tested GPU**: NVIDIA GeForce RTX 3060 (12 GB VRAM) on Windows 11 Pro 64-bit. * **In-Game Testing**: * Cycled between Minimum, Low, Balanced, High, and Ultra across Kokiri Forest, Hyrule Field, and Castle Town. * Confirmed proper texture retention without micro-stutters or texture streaming hitches. * Verified that manual alteration of resolution or upscaler instantly disengages the preset and switches label to Custom.

Commenting is not possible because the repository is archived.

No reviewers