feat(gpu): add a relative pointer option for virtio-GPU VMs - #181
Merged
Merged
Conversation
The virtio-GPU path attaches a virtio-tablet, an absolute pointer. That is right for a desktop — the host cursor maps onto the guest with no grab — but Wayland compositors deliver absolute motion with a zero relative delta, and a game that locks the pointer for mouse-look reads relative deltas only, so the camera never moves. Observed with Elden Ring under Proton on a gaming-arch VM: keyboard fine, mouse cursor visible, no look. Add gpu.pointer (tablet | mouse). "mouse" attaches virtio-mouse-pci, a relative pointer: the QEMU window grabs the cursor on click and forwards deltas, Ctrl+Alt+G releases. Exposed as --pointer on create, as pointer on the MCP create tool, and as `vee config <vm> --pointer` for existing VMs; QEMU cannot swap input devices live, so that applies on the next start. Like the GL knobs it is refused outside --gpu-mode=virtio, and an unknown device name is refused up front. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011c6BRY7R2svSu26ugUstV6
GTK3 cannot lock or warp the cursor on a Wayland host, so QEMU's GTK mouse grab never captures motion and a virtio-mouse receives no deltas — the relative pointer worked from QMP but not from a real mouse. QEMU's SDL2 display implements relative mouse mode with native pointer lock on both Wayland and X11, so pointer=mouse now selects -display sdl on Linux. The QEMU child gets SDL_VIDEODRIVER=wayland when the session is Wayland and the user has not set a driver, so SDL does not fall back to X11 via Xwayland. macOS keeps cocoa. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011c6BRY7R2svSu26ugUstV6
With a virtio-mouse attached, the Linux guest's psmouse driver still probes
QEMU's VMware backdoor port, finds vmmouse, and binds it to the PS/2 port.
QEMU's vmmouse is an absolute pointer, and once the guest activates it QEMU
makes it the current mouse ("info mice": "* vmmouse (absolute)"), so host
motion from the SDL window arrives as absolute coordinates again — zero
relative delta in kwin, no mouse-look — while QMP-injected relative events
still reached the virtio-mouse and looked fine.
Boot pointer=mouse VMs with -machine ...,vmport=off on x86 boards so there
is no vmmouse to bind. Left alone when the machine type already pins a
vmport= value, and never added off x86. Verified live: switching QEMU's
current mouse back to the virtio-mouse restored mouse-look immediately.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c6BRY7R2svSu26ugUstV6
Benehiko
force-pushed
the
feat/pointer-device
branch
from
September 6, 2026 10:32
4b50aff to
a9ea80d
Compare
Games lock the pointer for mouse-look and read relative deltas, which the absolute tablet never produces on a Wayland guest, so a gaming VM created with the default pointer starts with a camera that cannot turn. Make the gaming-arch template's virtio configuration ask for pointer=mouse (relative virtio-mouse, SDL window, vmport off); --pointer tablet on create restores the desktop-style pointer. Every other template keeps tablet. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011c6BRY7R2svSu26ugUstV6
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
On a virtio-GPU gaming VM, games that lock the pointer for mouse-look (Elden Ring under Proton here) get keyboard input and a visible cursor but the camera never moves. vee attaches
virtio-tablet-pci, an absolute pointer. KWin (and other Wayland compositors) deliver absolute motion with a zero relative delta, and a pointer-locked client reads relative deltas only.Change
gpu.pointer: tablet | mouse(defaulttablet, unchanged behaviour).mouseattachesvirtio-mouse-pci: the QEMU window grabs the cursor on click and forwards deltas; Ctrl+Alt+G releases the grab.vee create --pointer mouse,pointeron the MCP create tool, andvee config <vm> --pointer mousefor existing VMs (applies on next start; QEMU cannot swap input devices live).--gpu-mode=virtio, like the GL knobs; unknown device names refused up front.vm-yamlgpu table.Verification
vee config venus-test --pointer mouse, restart, guest showsQEMU Virtio Mouse; Elden Ring in a loaded world, 12 relative-x events via QMPinput-send-eventturned the camera (frame diff 77% in the play region, compass heading changed). Same input on the tablet device did nothing.make lint,go test ./...pass.🤖 Generated with Claude Code
https://claude.ai/code/session_011c6BRY7R2svSu26ugUstV6