Skip to content

android: A61, while the guest presents on its override surface, its window's X commits wait - #37

Closed
utkarshdalal wants to merge 1 commit into
gamenativefrom
override-frames-beat-x-commits
Closed

utkarshdalal wants to merge 1 commit into
gamenativefrom
override-frames-beat-x-commits

Conversation

@utkarshdalal

@utkarshdalal utkarshdalal commented Nov 13, 2026 •

Copy link
Copy Markdown

What happens today

Every game runs inside Wine's virtual desktop, so the desktop window is the only top-level gamescope manages, and the gamenative-drm shim binds its override surface (gamescope_swapchain.override_window_content) to it. For a Vulkan surface Wine considers offscreen (Wine 11: a swapchain on a child HWND, always; Wine 9 without XComposite: once a child window exists), Wine copies the X client window into the top-level after every present. On our route that X window never gets the guest's pixels, so the copy is black, damages the whole window, and Xwayland commits it on the main surface right after the override commit. get_window_last_done_commit() is last-done-wins across both surfaces, so the panel shows whichever finished last.

Measured on a Retroid Pocket 6: OMORI (NW.js, D3D11 on a child window, Wine 11) about 95 % of displayed frames were the black desktop, Portal 2 on Wine 9 about 83 %. Setting gamescope_surface_update_force_only_current_surface=true on OMORI gave 476 of 476 game frames, full-screen, 60 fps. That proves the cause, but as a default it hides X content forever, for example a Wine message box the game blocks on (the game stops presenting, so nothing else would ever be shown).

Upstream's WSI layer sidesteps this by not bypassing Xwayland for such windows (canBypassXWayland), which here would put the game in its small Wine window on the virtual desktop instead of full-screen, so this keeps the direct route.

What the patch does

android/patches/gamescope/0054-A61-override-commits-beat-x-commits.patch, in update_wayland_res() / check_new_xwayland_res():

  • Each window records when its override surface last committed. Frame-generation commits arrive on the same surface and count.
  • While that is within surface_update_override_hold_ms (new convar, default 500, 0 = off; env gamescope_surface_update_override_hold_ms), a damaged main-surface commit that the existing rule would have accepted is held: its presentation feedback is discarded and receivedDoneCommit is set right away (as the existing drop path does, so frame callbacks keep flowing), but the wlr_buffer lock is kept and the entry is parked per window. Only the newest is kept; the older one's buffer is unlocked when it is replaced.
  • Once the override has been quiet for the hold time, the parked commit is pushed through update_wayland_res() at the start of the next check_new_xwayland_res() (every main-loop pass, so at worst a vblank late), before that round's new commits, so X content comes back without new X damage and anything newer still lands after it. When the override commits again its frames are newer and take over.
  • A parked commit is released (unlocked, never shown) when a main-surface commit goes through normally (it is stale then), when the window is destroyed (finish_destroy_win), when its surface is no longer the window's main surface, or when the existing current-surface rule would never show it (non-sRGB colour space seen, or the force convar set).
  • Nothing changes without an override bound, nor for override commits. Commits the existing rule drops (no damage, bogus 1-2 px, non-sRGB, force convar) are still dropped, not held. surface_update_force_only_current_surface keeps its meaning.

Why 500 ms: a game that is presenting delivers a frame every 8-50 ms and a compile/streaming hitch rarely blocks for more than a few hundred ms; longer than that is the game not presenting (dialog, pause, crash, exit), and a dialog half a second late is fine. A hitch longer than that shows the latest X content (on these titles the black copy) until the next game frame.

Two one-shot info lines per window prove the patch is live: override-hold: window 0x... holds back main-surface commits while its override surface presents and override-hold: window 0x... override quiet for 500 ms, showing the held main-surface commit.

android/README.md gets a short section on the two surfaces and the hold.

Interactions checked

  • A33 session blanking (session-blank:): the startup blind lifts on the first commit newer than the binding; override commits are never held, so that is unchanged, and Wine's black copies can no longer lift it early. A GL guest with a dormant Vulkan swapchain (the Tomb Raider case) never commits on the override, so its X commits are never held. Exit: when the shim destroys the override, main commits are no longer "not for the current surface" and go through as before (releasing anything parked); if no new X commit comes, the parked one is shown once the hold time has passed since the last override commit, which counts as "painted after the gap" for A33's exit arm, i.e. the blind is raised, which is what exit wants. A short recreate gap (device loss, new surface) under 500 ms shows nothing held.
  • A43 (disabled) and A48: A48 only sends winhandler a bring-to-front on MapNotify of nested windows; no commit path. A49 touches finish_destroy_win for the reaper kick; the release is added after the commit queue clear, independent of it.
  • A51/A55 (scan-out stride, cursor plane) and A46: paint/scan-out side only; which commit is the latest done is decided before them.
  • bHasHadNonSRGBColorSpace: still drops main commits outright, and a parked commit is not shown after it became set.

Verified

  • The series applies in filename order with git apply --check onto a clean export of gamenative (34 patches incl. this one), the same way build-gamescope.sh applies it, and the patched files match the tree the diff was generated from.
  • No local compile (no NDK/termux prefix on this machine); the Android build workflow compiles it.
  • On a Retroid Pocket 6 with the CI binary from this PR (gamescope md5 fb11fb7e4439d30d0278f1a3f8d041db) dropped into the installed payload: OMORI on Wine 11 runs full-screen with no flashing. An 8 s recording at the title screen has 0 of 460 frames showing the black desktop (before: about 95 %), 60 fps on the HUD, and the daemon publishes about 589 frames per 600 vsyncs. The log has the hold line once (override-hold: window 0x600004 holds back main-surface commits while its override surface presents) and the release line once, 510 ms later, in the gap between OMORI's first and second swapchain at startup; none after that.
  • Not yet checked on a device: Portal 2 on Wine 9, a game that shows a Wine dialog or launcher window (should still appear within about half a second), exiting a game (no stuck frame, A33 blind still raised), frame generation on, and what a loading pause longer than the hold time looks like.

Note: android/patches/diagnostics/0023-A23-present-path-diagnostics.patch already fails to apply on gamenative without this change.

…'s X commits wait (A61)

Wine copies an offscreen Vulkan child window into the virtual desktop's
top-level after every present. On the override route that copy is black and
lands on the window's own surface right after the guest's frame, so
last-done-wins showed the black desktop most of the time (OMORI ~95 %,
Portal 2 on Wine 9 ~83 %).

While the override surface has committed within
surface_update_override_hold_ms (default 500), damaged main-surface commits
are held instead of shown, the newest one kept with its buffer locked. Once
the override is quiet that long the held commit is shown without new X
damage, so a dialog the game blocks on still appears. The README documents
the two surfaces and the hold.
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.

2 participants