Skip to content

Move the frame dump and GPU capture hotkey to Ctrl+Shift+P - #1076

Merged
athei merged 1 commit into
mainfrom
capture-hotkey-p
Oct 6, 2026
Merged

athei merged 1 commit into
mainfrom
capture-hotkey-p

Conversation

@athei

@athei athei commented Oct 6, 2026

Copy link
Copy Markdown
Owner

Symptoms

Ctrl+Shift+F7 (#1075) does not arm the frame dump and GPU capture, because the key never reaches Wine. A game run with Wine's +key trace shows Fn+F7 alone arriving as press 98 (kVK_F7), but with Control and Shift held Wine receives only the Shift (56) and Control (59) presses and no F7. Ctrl+Shift+F6 delivers nothing either.

macOS takes Ctrl+F1 to Ctrl+F8 for its keyboard-navigation shortcuts and still takes them with Shift held. The Metal HUD's menu takes Shift+F8 to Shift+F12 and Ctrl+Shift+F9 to Ctrl+Shift+F12, and Steam takes a bare F12. So no Ctrl+Shift function-key chord reaches the game.

Changes

The hotkey is now a fixed Ctrl+Shift+P: P going down while Control and Shift are held and Alt is up (winemac reports either Command key as Alt). The edge semantics are unchanged: a held chord fires once, Control and Shift pressed after P is already down never fire, and the modifiers are read only on the present where P goes down. CAPTURE_KEY in windows/core/src/capture_chord.rs becomes VK_P (0x50); windows/d3d9/src/capture.rs already reads it from there, so only its comments change.

P sits at the same place on QWERTY, QWERTZ and AZERTY, so its virtual-key code does not move with the keyboard layout, and as a letter it needs no Fn on a MacBook keyboard. macOS, the Metal HUD and Steam do not use it, and games that bind P rarely bind Ctrl+Shift+P.

The unit tests in capture_chord/tests.rs check that Ctrl+Shift+P fires once per press and not while held, and that P, Shift+P, Ctrl+P and Ctrl+Alt+Shift+P do not. They also check that the chords that never reach Wine do not fire: F12, Ctrl+Shift+F12, the old Ctrl+Shift+F7, the HUD's Shift+F8 to F12 and Ctrl+Shift+F9 to F12, and Ctrl+F1 to F8 with or without Shift. The tests for modifiers pressed after the key and for reading modifiers only on the press are kept.

Every doc and comment that named Ctrl+Shift+F7 now names Ctrl+Shift+P: the README, docs/ARCHITECTURE.md (section heading and its anchor), the link to it in docs/GAMES.md, CONTRIBUTING.md, the bench-shape text in the Makefile, mtld3d.conf, the bench runner's messages and the code comments on both sides. The README and the architecture section give the new reason (Steam's F12, the HUD's Shift+F8 to F12 and Ctrl+Shift+F9 to F12, and macOS's Ctrl+F1 to F8, which it takes even with Shift held), say that P sits at the same place on the common layouts, keep the Control-not-Command note, and drop the MacBook Fn note.

Alternatives considered

Another function key: Ctrl+F1 to F8 belong to macOS with or without Shift, Ctrl+Shift+F9 to F12 to the HUD, and F12 to Steam, so every Ctrl+Shift function-key chord is taken before Wine sees it. A different letter: a letter that moves between QWERTY, QWERTZ and AZERTY (such as Y, Z, A, Q or M) would put the chord on a different key position, or a different virtual-key code, depending on the layout, while P does not move. A configurable key was not added: the chord stays fixed, with no config key and no environment variable.

Verification

make fmt, make check (rustfmt, clippy with nursery and pedantic on both workspaces and the PE targets, make audit, make doc) and make test-unit ran green: 1972 windows-workspace tests, including the 14 capture_chord tests, and 755 unix-workspace tests passed. No end-to-end test uses the hotkey, so make test was not run.

The reason for the change comes from the +key trace above: Fn+F7 alone reaches Wine as press 98, Ctrl+Shift+F7 and Ctrl+Shift+F6 deliver only the modifier presses. Ctrl+Shift+P was pressed in World of Warcraft 1.12 with Wine's +key trace on, and Wine received press 59 (Control), press 56 (Shift) and press 35 (kVK_ANSI_P) with modifiers 0x00060103, so P arrives with Control and Shift held. The build installed for that run predates this change, so the dump itself has not fired from the new chord yet; a reviewer can check it by pressing Ctrl+Shift+P in a game started with MTL_CAPTURE_ENABLED=1 and looking for the [dump] lines and a <exe>-<pid>-<n>.gputrace beside the log.

Rules check

The change adds no static, config key, environment variable, wire field, dependency, derive or lint suppression, and duplicates nothing: it changes the value of the existing CAPTURE_KEY in mtld3d-core and the existing per-poll latch keeps its doc-block argument. The tests stay in capture_chord/tests.rs (Unit tests live in <stem>/tests.rs), and doc blocks keep the title, blank, body shape. make check enforces these through clippy, make audit and make doc, and it ran green.

Ctrl+Shift+F7 never reaches Wine. With Wine's +key trace, Fn+F7 alone
arrives as press 98 (kVK_F7), but with Control and Shift held Wine
receives only the Shift (56) and Control (59) presses and no F7, and
Ctrl+Shift+F6 likewise delivers nothing. macOS takes Ctrl+F1 to Ctrl+F8
for keyboard navigation even with Shift held, the Metal HUD's menu
takes Shift+F8 to Shift+F12 and Ctrl+Shift+F9 to Ctrl+Shift+F12, and
Steam takes a bare F12, so no Ctrl+Shift function-key chord is free.

The hotkey is now P going down while Control and Shift are held and
Alt (which winemac maps from Command) is up, with the same edge
semantics: a held chord fires once, modifiers pressed after the key
never fire, and the modifiers are read only on the sample where the
key goes down. P sits at the same place on QWERTY, QWERTZ and AZERTY,
so VK_P (0x50) does not move with the layout, and it needs no Fn.

The unit tests check that Ctrl+Shift+P fires once per press and that
P, Shift+P, Ctrl+P, Ctrl+Alt+Shift+P, F12, Ctrl+Shift+F12, the old
Ctrl+Shift+F7, the HUD's Shift+F8 to F12 and Ctrl+Shift+F9 to F12,
and Ctrl+F1 to F8 with or without Shift do not. Every doc and comment
that named Ctrl+Shift+F7 now names Ctrl+Shift+P, and the README and
the architecture notes give the new reason and drop the MacBook Fn
note.
@athei
athei merged commit d8e52da into main Oct 6, 2026
14 checks passed
@athei
athei deleted the capture-hotkey-p branch October 6, 2026 13:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant