Wayland Support on Linux

Recently we have been working on native Wayland support on Linux.

Wayland is now enabled for daily builds and if all goes well, it will be enabled for Blender 3.4 release too.

If you’re a Wayland user, try a recent build.

• The library libdecor needs to be installed.
• To see if native Wayland is used, check the “About” splash (accessed from the “Blender” icon menu, top left). You should see:
  “Windowing Environment: WAYLAND”.

Please report bugs for any Wayland specific issues you run into.

Why Wayland?

Even though Wayland has existed since ~2008 as a replacement for X11, it’s only recently that some Linux distributions have been enabling it by default.

Long term, native Wayland support should give us the best user experience, allowing Blender to support features exposed by Wayland without being limited by the X11 compatibility layer.

Why not SDL?

It’s possible for Blender to be built against SDL – a cross-platform library that interfaces multiple windowing environments, handle user input … etc. A case can be made for avoiding the work of supporting Wayland directly and using a library that abstracts away the platform specific details.

The challenge with using 3rd party libraries for windowing is it can make using platform spesific features more difficult. Blender also uses input devices SDL doesn’t support: tablets & NDOF (3D-mouse) devices.

Nevertheless, we seriously considered using SDL, concluding that it would require us becoming SDL developers to properly support Blender. As SDL’s focus is on gaming, this isn’t necessarily aligned with the needs of applications – so we felt it best to continue using native support for the windowing environment.

Some Back Story

Initial support for Wayland landed back in 2020 (big thanks to Christian Rauch for his contributions).
While supported as a build option, there were various TODO’s left which we have been resolving in an effort to have Wayland supported well enough for it to enable it by default in our official releases.

Examples of remaining issues included:

• No tablet support.
• No NDOF (3D mouse) support.
• No cursor warping.
• No window frames.
• No Hi-DPI support.
• Wayland was a requirement, even for X11 or users running Blender on render-farms.

See the GHOST/Wayland Support task for a full list of TODO’s.

Around May this year I tried switching to Wayland entirely (no XWayland), as I had upgraded my computer and switched to an AMD graphics card (which runs Wayland well). Emacs had just added native Wayland support so there wasn’t anything holding me back.

Since then I’ve been using Wayland exclusively, fixing issues when they arise and investigating bugs reported by users.

Now Wayland is enabled in our official builds, I hope to validate it for the up coming release. So unless issues arise which we’re unable to resolve, it will be officially supported in Blender 3.4x onward.

Technical Details

• Wayland has some intentional constraints that impact Blender, for example:
  • Setting the cursor position directly isn’t supported. To support cursor warping the cursor is locked in-place, then a virtual cursor is drawn in software for e.g.
  • Positioning windows on a particular monitor or relative to other windows isn’t supported. This means dragging content (color, icons in the outliner … etc) isn’t supported between windows. We have to use system-level drag events (the same kinds of drag & drop support used by file browsers) – something Blender should be doing anyway.
  • Gnome-shell has decided not to support server side decorations, meaning it’s up to each application to define it’s own window frame (title bar & window borders). For developers of tool-kits such as GTK/QT, this makes some sense as they can build window drawing into their toolkit. For a cross-platform applications like as Blender it isn’t so convenient, although longer term we might look into client-side decorations. For now we’re using libdecor and we’ll see how it evolves.
• Initially Wayland was difficult to troubleshoot, when something went wrong often the window would just close without a crash or warning that pointed to the problem. Eventually I found wl_log_set_handler_client could be set (which now prints a stack-trace to help track down issues). So the situation isn’t as bad, although there are still a closing window issue that need investigation.
• While X11 carries many of it’s own quirks & historic baggage in practice we only needed to support a single implementation (Xorg). As Wayland has multiple compositors, each of these can behave differently calling event handlers in a different order or omitting some arguments. Although there are 3 main compositors: (gnome-shell, KDE & Sway (with various compositors based on Sway’s wlroots library). Hopefully these differences will be ironed out over time, for now we have to keep some workarounds for composites that misbehave (reporting bugs up-stream).
• Support for dynamically linking libwayland (and related Wayland libraries), proved to be much more of an ordeal than I’d expected (due to the API’s use of varargs), making it impractical to forward arguments without compiler specific workarounds. This was solved by replacing function calls in auto-generated headers, while not ideal it’s functional.
• Wayland development unexpectedly lead to fixing an 8 year old bug on MS-Windows. Supporting modifier key detection on Wayland involved changes to modifier handling on all platforms. I stumbled on error prone logic that caused issues with modifier key detection (commits 1, 2).

Campbell Barton

Australia, 11th October. 2022