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 (EDIT: now only for gnome-shell).
  • 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 specific 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 (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

  1. im more excited for this can yoou can imagine ahaha

  2. Blender
    is Better

  3. Thank for the quick fix, Campbell!

    Just joking -great work. I don’t use Fedora/Wayland anymore but the bug was still here on Windows. Mad thanks for tracking it down and making it but a memory. 🙏

    • Hah, well I don’t develop on Windows generally & needed to setup a VM just to compile the changes and check nothing broke, that lead to investigating some strange logic going on there which I normally wouldn’t touch.

  4. I really wanted the answer to “Why not SDL?” to be “If we had used SDL you’d be asking why not Wayland?”

    • While using SDL has pros and cons – I think switching to SDL for official releases would mean SDL would need focus more on application support. Further, I’d be more interested to use SDL if we could replace native support on all platforms (so MS-Windows and Apple too) this would reduce the maintenance overhead for supporting different platforms, otherwise having only Wayland use SDL isn’t a significant benefit.

      If we switched to SDL on all platforms we end up with a TODO list: to support features previously supported on each platform (tablet support, parent/child windows, progress in MS-Windows taskbar… etc).

      While SDL can of course be extended to support these features it’s not a drop-in replacement for us at the moment.

  5. At this point, it seems more logic for me if the app code instead of render & collect user-i/o, just derive those data flows in ‘n’ out with main sys. webexplorer.

    It will follow what user configured in sys and what sys could have native or updated.

    👍 Thanks 4 such article

  6. Wow, thank you! I genuinely thought i won’t see it during my life time. And it appears russian rockets and drones stop flying today. What a great day.

  7. Very exciting news, especially as a Sway and Blender user!

    • While testing Wayland support I’ve been impressed by the high quality of Sway and wlroots based compositors in general. Most of the bugs we’ve had to workaround have been with Gnome-shell, although they’re fixing issues so I’m not too worried.

  8. Excited to hear this. Thank you so much for the hard work!

  9. This is great news! Open source ftw! <3

  10. Thank you for your hard work.

In order to prevent spam, comments are closed 15 days after the post is published.
Feel free to continue the conversation on the forums.