Support presenting to a native Wayland surface on Qt

[hmaarrfk]

xref: #36

got to test this on an actual linux machine soon running wayland. Curious to see this in action, but the commits look good.

• CI Tested on qt+x11
• CI Tested on qt+xwayland
• CI Tested on qt+wayland

Claude's notes

What this does

On Wayland, rendercanvas puts Qt on XWayland, and the code to present to a native Wayland surface is disabled with an if False. That code could not have worked: it pairs the wl_surface from winId() with a display from get_alt_wayland_display(), i.e. a fresh wl_display_connect(). A wl_surface is a proxy owned by the connection that created it, so libwayland aborts with Proxy and queue point to different wl_displays as soon as a buffer is attached. The existing comment ("this segfaults, so it looks like the real display object is needed?") diagnosed this correctly.

Worth noting for anyone testing this: creating the surface succeeds with the wrong display, and so does wgpuSurfaceGetCapabilities. It only aborts once frames are actually presented, so a probe has to render.

Qt can say what display it is connected to, and that display is the only one its surface is valid on. So this:

• gets the real wl_display from Qt (QNativeInterface::QWaylandApplication on Qt6, the platform native interface on Qt5);
• decides the platform from the qpa plugin Qt actually uses rather than from sys.platform, since under a Wayland session Qt may still be on XWayland, where winId() is an X11 window;
• only puts Qt on XWayland when the Qt lib cannot provide its display, so those libs keep using the x11 code-path. Qt picks its platform when the application is instantiated, so this is decided at import-time.

A second bug this uncovered

WgpuContextToScreen._rc_close unconfigured the wgpu context but never released the surface, leaving it to the garbage collector. On Wayland the surface belongs to the toolkit's display-connection, so during interpreter shutdown wgpuSurfaceRelease ran after Qt had torn that connection down — a use-after-free (gdb showed the freed map was Qt's wl_display + 0x90). x11 never hit this because an X11 window id is just a number that outlives any connection. This was unreachable before, so it is newly-exposed rather than a regression.

Which Qt versions get native Wayland

QNativeInterface.QWaylandApplication turns out to be recent. Checked each PySide6 minor:

PySide6	QNativeInterface	QWaylandApplication	result
6.11, 6.10	yes	yes	native Wayland
6.9, 6.8, 6.7	yes	no	XWayland
6.6, 6.5	no	no	XWayland

So most installs today keep the current behaviour, and this is a no-op for them. It also means the check has to be for QWaylandApplication specifically: QNativeInterface alone exists since 6.7 and would be a false positive on 6.7–6.9.

Behaviour changes worth a look

• An explicit QT_QPA_PLATFORM is no longer overridden. Previously QT_QPA_PLATFORM=xcb was set unconditionally under Wayland, so a user asking for wayland was silently overruled. Forcing still works in both directions.
• The _get_surface_ids → None → bitmap path is now only reachable when a QApplication already exists at import (already_had_app_on_import) with a Qt lib that cannot provide its display. It is too late to force xcb there, so degrading to bitmap beats crashing.
• wgpucontext.py is shared with glfw. Releasing the surface at close rather than at GC is correct for every backend, but it is not Qt-only code. Happy to split it out.

Testing

Tested against a headless weston with lavapipe (software Vulkan), on PySide6 only, since that is all that was installed locally. Presenting to screen works for both a top-level canvas and an embedded QRenderWidget, and the teardown crash is gone. tests/test_backend_qt.py passes on native Wayland and on xcb. The rest of the suite is unchanged (the 3 test_meta failures locally are a pre-existing git-version mismatch, identical on a stashed baseline).

The second commit adds a test-qt-linux job covering the three cases: Wayland with a capable Qt, Wayland with PySide6 6.9 (must fall back to XWayland), and x11-only. Each case asserts which qpa platform Qt ends up on before running the tests, because a case that silently fell back would otherwise still pass and test nothing. I checked the assertion actually fails the step when the platform is wrong.

The jobs were validated by running the same steps in ubuntu/python docker images, which turned up two things worth knowing: the pip PySide6 wheel does ship libqwayland.so, and Qt's xcb plugin needs libxcb-cursor0 (Qt >= 6.5), which the existing dependency list does not install.

Not addressed

glfw and wx are untouched and stay on XWayland, so they are not equivalent to Qt after this. Neither exposes the display of its connection (glfw could via glfw.get_wayland_display(), wx has no way at all). glfw on Wayland was not testable here: glfw.init() hangs under headless weston because libdecor cannot initialise GTK, before rendercanvas is involved.

[hmaarrfk]

On the main branch, you get the X11 decorations

On this branch you get the wayland side client side decorations

[hmaarrfk]

This is ready for review

[hmaarrfk]

@almarklein this is the shadiest part abut this code.

[hmaarrfk]

https://github.com/pygfx/wgpu-py/blob/main/wgpu/backends/wgpu_native/_api.py#L1049

but AI was convinced that sometimes this method did not exist.

I would love to see native support for qt-wayland especially since x11 is being moved away from so quickly.