feat(menu): a V-Sync row (Auto, On, Off) #2041

Merged

hckrman101 merged 2 commits from menu/vsync-row into main

2026-11-11 03:04:55 +00:00

hckrman101 commented

2026-11-11 00:50:56 +00:00

(Migrated from github.com)

The present mode (V-Sync) could only be chosen with two undocumented environment switches. Players who see tearing, or who want the least delay, had no menu option for it.

This adds a V-Sync row on the Graphics tab, under Frame pacing:

Auto (default): what the renderer chose before. Mailbox where the driver has it, else FIFO; on Windows, immediate where there is no mailbox (AMD).
On: FIFO. Each frame waits for the display's refresh: no tearing, at most the display's rate.
Off: immediate where the driver has it, else as Auto. The least delay, and it can tear.

It applies at once: the swapchain is made again, as it is for an HDR change. It is saved as vsync= and leaves the Quality preset alone. RX_VK_FIFO=1 (On) and RX_VK_IMMEDIATE=1 (Off) still choose for a run. They apply where the mode is chosen (menu_vsync), so they never reach hookshot_options.ini. The swapchain's log line now names the row's choice, for example vk: swapchain 1916x1051, 4 images, fifo (V-Sync On). The readme's menu table and notes and the development guide list the row and the two switches.

Tested

Linux, RTX 3090, current main:

Build: a full build of the game and hookshot_vk.so, with the shaders prepared.
Checks: python -I -B tests/run_all.py: 339 passed, 13 skipped. The three failures (nx2/test_nup_read_name, tests/test_builder_log_read_only, tests/test_wayland_libdecor_hint) also fail on main on this machine.
tests/test_vsync_row.py checks the row, its key, and the environment's precedence. It also runs create_swapchain's own choice of mode over the lists drivers give (all three modes, no mailbox, FIFO only), as on Windows and as on Linux.
In game, with the game's window in a private Wayland compositor (sway, headless backend), so the swapchain is real:
- The row at Auto gave mailbox (V-Sync Auto).
- Changing it in the menu to On and then Off made the swapchain again each time, as fifo (V-Sync On) and then immediate (V-Sync Off), with no errors, and the options file then held vsync=2.
- RX_VK_FIFO=1 over a saved vsync=2 gave fifo (V-Sync On), and the file kept vsync=2.
- RX_VK_IMMEDIATE=1 over a saved vsync=0 gave immediate (V-Sync Off), and the file kept vsync=0.

Not tested

Tearing itself, which needs a run on a visible display.
Windows, AMD and Intel cards.
X11.

The modes a driver offers differ, which is why the choice falls back as described above.

The present mode (V-Sync) could only be chosen with two undocumented environment switches. Players who see tearing, or who want the least delay, had no menu option for it. This adds a **V-Sync** row on the Graphics tab, under Frame pacing: - **Auto** (default): what the renderer chose before. Mailbox where the driver has it, else FIFO; on Windows, immediate where there is no mailbox (AMD). - **On**: FIFO. Each frame waits for the display's refresh: no tearing, at most the display's rate. - **Off**: immediate where the driver has it, else as Auto. The least delay, and it can tear. It applies at once: the swapchain is made again, as it is for an HDR change. It is saved as `vsync=` and leaves the Quality preset alone. `RX_VK_FIFO=1` (On) and `RX_VK_IMMEDIATE=1` (Off) still choose for a run. They apply where the mode is chosen (`menu_vsync`), so they never reach `hookshot_options.ini`. The swapchain's log line now names the row's choice, for example `vk: swapchain 1916x1051, 4 images, fifo (V-Sync On)`. The readme's menu table and notes and the development guide list the row and the two switches. ## Tested Linux, RTX 3090, current `main`: - **Build:** a full build of the game and `hookshot_vk.so`, with the shaders prepared. - **Checks:** `python -I -B tests/run_all.py`: 339 passed, 13 skipped. The three failures (`nx2/test_nup_read_name`, `tests/test_builder_log_read_only`, `tests/test_wayland_libdecor_hint`) also fail on `main` on this machine. - **`tests/test_vsync_row.py`** checks the row, its key, and the environment's precedence. It also runs `create_swapchain`'s own choice of mode over the lists drivers give (all three modes, no mailbox, FIFO only), as on Windows and as on Linux. - **In game**, with the game's window in a private Wayland compositor (sway, headless backend), so the swapchain is real: - The row at Auto gave `mailbox (V-Sync Auto)`. - Changing it in the menu to On and then Off made the swapchain again each time, as `fifo (V-Sync On)` and then `immediate (V-Sync Off)`, with no errors, and the options file then held `vsync=2`. - `RX_VK_FIFO=1` over a saved `vsync=2` gave `fifo (V-Sync On)`, and the file kept `vsync=2`. - `RX_VK_IMMEDIATE=1` over a saved `vsync=0` gave `immediate (V-Sync Off)`, and the file kept `vsync=0`. ## Not tested - Tearing itself, which needs a run on a visible display. - Windows, AMD and Intel cards. - X11. The modes a driver offers differ, which is why the choice falls back as described above.