Skip to content

shim: a swapchain takes its window at its first present, not at surface creation - #64

Closed
utkarshdalal wants to merge 1 commit into
masterfrom
shim-bind-window-at-first-present
Closed

utkarshdalal wants to merge 1 commit into
masterfrom
shim-bind-window-at-first-present

Conversation

@utkarshdalal

@utkarshdalal utkarshdalal commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

One commit on top of master.

The failure

Alex Kidd in Miracle World DX (Epic) freezes on a black screen about 10 s after start under gamescope when the Epic overlay is on. It runs with the overlay off, and on the X11 display server.

gamescope keeps one override surface per X window: handle_override_window_content drops the previous binding (sends retired) when a new one arrives, and the old surface's later commits sit in g_PendingCommits with their buffers locked. The shim sent override_window_content as soon as the Vulkan surface was created. The overlay DLL creates a D3D11 device and swapchain on a child of the game's window only to find Present, destroys it 7 ms later and never presents. The child resolves to the same top-level, so that throwaway surface took the game's window. From then on the window was bound to a surface with no content (black), none of the game's five images came back (in_flight=5), and the next acquire waited forever.

The shim also never told gamescope a surface was gone: vkDestroySurfaceKHR only freed the client proxies, so the binding and the server-side surface stayed alive for the rest of the session.

The change

  • override_window_content goes out right before a swapchain's first commit (bind_window_at_first_commit, on the worker, inline and generated-frame commit paths), once per swapchain. A swapchain that never presents never takes the window. A recreated swapchain on the same surface (resize, present-mode change) re-sends it, which gamescope ignores for the surface that already holds the window. Server-side the order is unchanged: bind, then the first attach + commit in the same flush.
  • vkDestroySurfaceKHR sends gamescope_swapchain.destroy and then wl_surface.destroy (both opcode 0, no args). Swapchain first, so gamescope drops the content override without finishing the window's X11 surface info.
  • docs/13 step 4 describes when the binding is made.

Not in this PR: a gamescope_swapchain.retired listener. A swapchain whose window is taken by another one that really presents still stalls in acquire if it keeps presenting, as before. Handling it needs a listener with all three events, a wake of the acquire wait, and VK_ERROR_OUT_OF_DATE_KHR from acquire/present, which is more than this fix.

What the deferral changes in gamescope's A33 session blind: the binding is stamped at the first paint that sees it, which is now at most one frame later. A surface destroyed while its window lives on now leaves the window unbound, so A33 holds it black until the next swapchain's first commit, where before it kept the last frame.

How to test

  • Built for aarch64-linux-android (release, NDK 27.3) at 341d3d0, export set unchanged, clippy -D warnings clean for adrenotools_gamescope (all targets). Merges cleanly with Shim waits for the panel to release a buffer before the guest renders into it #60 and shim: at a cap at the display's rate, a self-paced guest keeps the container's mode with the vblank-grid gate #61. Lib tests not run.
  • Retroid Pocket 6, payload 20261105.4 with only libadrenotools_gamescope.so replaced, Alex Kidd in Miracle World DX, gamescope, Epic overlay on, GNDRM_LOG_VKSHIM=1:
    • the game's swapchain binds at its first commit: override: swapchain 0x...ae50 binds surface 0x...4500 to XID 0x600004 at its first commit;
    • 8 s later the overlay's swapchain on XID 0xe0005e (same top-level 0x600004) is created and destroyed with no bind line (one bind line in the whole session);
    • releases keep pace: acq=30 pres=29 rel=28 in_flight=1 right after the probe, acq=6477 pres=6476 rel=6475 in_flight=1 110 s later. Before the fix the same point stuck at rel=28 in_flight=5.
    • HUD 60.0 fps on the main menu through the session; app session stats 159 s / 57.7 avg fps / 7773 frames (unlogged run: 182 s / 58.1 / 9156). Before the fix: 36 frames.
    • Same result on Proton 11 (proton-11.0-2-arm64ec-9): the probe swapchain is 2x2 there and is not bound either; 172 s / 57.7 avg fps.
  • Not covered: a second swapchain on the same window that really presents (still stalls the earlier one, as before), surface recreation inside a running game, frame generation's first commit, and other games.

…urface creation

gamescope keeps one override surface per X window, and a new
override_window_content retires the previous binding. The shim sent it as
soon as the surface was created, so any surface made for the game's window
took the window, whether or not it ever presented. The Epic overlay does
exactly that: it creates a D3D11 device and swapchain on a child of the
game's window only to find Present, destroys it 7 ms later, and never
presents. The child resolves to the same top-level, so the throwaway
surface stole the game's binding; the game's later commits sat in
gamescope's pending list with their buffers locked, all five images stayed
in flight, and the next acquire waited forever on a black screen.

The binding now goes out right before a swapchain's first commit (worker,
inline and generated-frame paths), once per swapchain; gamescope ignores a
repeat from the surface that already holds the window, so a recreated
swapchain on the same surface costs nothing.

vkDestroySurfaceKHR now sends gamescope_swapchain.destroy and
wl_surface.destroy instead of only freeing the client proxies, so the
compositor drops the binding and the surface instead of keeping both alive
for the rest of the session.
@joshuatam

Copy link
Copy Markdown
Collaborator

Reviewed #64 and ran it on device with an Epic-overlay title (Alex Kidd's failure mode). The binding placement is right and I'm not arguing with it — two things suggested on top, in #65: keep defaulting the id to the first commit, and it is worth stating why the destroy order is load-bearing.

What #64 gets right, and now measured. With the overlay on, Yooka-Laylee creates two surfaces for the same top-level (0x1400043 and 0x1400055 → 0x600004) and exactly one bind happens:

override: swapchain 0xb400007889064450 binds surface 0xb4000078e902e510 to XID 0x600004 at its first commit

FINAL FANTASY VII REMAKE INTERGRADE (vkd3d/D3D12) goes further: one of its surfaces, …9010 for XID 0x1400019, never binds at all, because it never paints — while the other surface owns the window. That is the throwaway-surface case in a second title, and it is the case the pre-#64 placement loses.

Suggestion 1 — the id is decided too early, the binding is not. resolve_override_target runs at surface creation and its answer is frozen into GnSurface.window; it has to run there, because a surface answers caps and surface_extent reads the window's live size. On the legitimate path that is fine: under wine explorer /desktop=shell the root-child ancestor is the one full-size desktop window, so the answer cannot change — measured on both titles, (legitimate; unchanged) every time, and no re-ask happened.

On the fallback path it is a guess: a degenerate ancestor (Dishonored under a 1×1 override-redirect helper) selects by pid, class, input focus and _NET_ACTIVE_WINDOW, read from a tree the guest has not drawn into yet. #64 already moved the bind past that moment; making the id decision at the same instant costs one X round trip only on the guests that took the fallback. That is what #65 does, with OverrideTarget { window, provisional } and a single re-ask in bind_window_at_first_commit.

Suggestion 2 — the destroy order deserves a comment in the code. It is correct as written, but the reason is not obvious and the failure is silent-ish:

swapchain.destroy → handle_resource_destroy → destroy_content_override
                     → wl_surface_info->x11_surface = nullptr      ← this is the guard
wl_surface.destroy → handle_wl_surface_destroy
                     → if (surf->x11_surface) …                     ← now skipped

Reverse the two and wl_surface.destroy reaches wlserver_x11_surface_info_finish(x11_surface), which tears down both overrides and re-inits the window's surface info — main_surface = nullptr, wl_id = 0, pending_link removed. The window loses its wine Xwayland surface for the rest of the session. One line above the two sends would keep the next reader from reordering them.

Cross-repo consequence worth linking. #64's teardown makes A33's "override is gone" state reachable mid-session, where it was exit-only before. That arm blanks the panel on absence alone, so a surface recreate now flashes black. gamescope #36 changes it to blank only once something else has painted after the gap; the two should land together.

Not covered by my run: a guest that destroys its Vulkan surface while its window lives (a DXVK/vkd3d device loss), which is the only path that exercises the gap. Swapchain recreates are fine — measured, proxy swapchain destroyed: … presents=1 commits=1 followed by a re-bind on the same surface, no unbind, no blank.

Device evidence, both titles, payload 20261110.1: fps 59.9–61.0 (Yooka-Laylee) and 30.0 with the limiter off (FF7, its own cap), stall signatures: 0, gamescope Error/Warn: 0, both with the Epic overlay on.

@joshuatam
joshuatam deleted the shim-bind-window-at-first-present branch November 11, 2026 02:56
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