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]

Kind ping here

[almarklein]

I'll have a proper look this Friday, and see if we can merge this before or after #227 (which creates backwards incompatible changes for backend implementations).

[almarklein]

Looks good to me. Tried on Ubuntu 24.04 with Wayland, and it works. The only thing is that with present_method='screen' the window initially has not minimize/close buttons. They appear as soon as the window loses focus. This might be a problem on my machine, since many widgets have no outer edge when I use Wayland.

If you can confirm that the buttons are there with present_method='screen', I'd consider that good enough. If not, we probably need to tickle Qt at window creation or something.

[hmaarrfk]

Looks good to me. Tried on Ubuntu 24.04 with Wayland

I'm not sure why your screenshot looses the close buttons but mine has them.... that is very strange. I've never seen that before.

I was on Ubuntu 26.04 (sorry i updated my machines)

[hmaarrfk]

Also, for the decorations to look more normal, apparently one needs to compile with qadwaita or something like that. a plugin that helps draw those decorations better by default.

[almarklein]

Also, for the decorations to look more normal, apparently one needs to compile with qadwaita or something like that. a plugin that helps draw those decorations better by default.

It's funny (or not) that stuff like this is still needed ... anyway, out of scope for rendercanvas (the qadwaita thing).