Wayland public preview branch

News and Announcements
1

We’re excited to announce that a preview of native Wayland support for JUCE is now available on a new public wayland branch of the JUCE repository.

If you develop standalone applications, audio software, or embedded Linux products, please give this branch a try!

Native Wayland by Default

When a standalone JUCE application starts in a Wayland session (WAYLAND_DISPLAY is set), JUCE will attempt to create native Wayland peers. If Wayland is unavailable, JUCE falls back to X11. The Wayland libraries are loaded at runtime, allowing the same
application binary to run in native Wayland, X11, and XWayland environments.

The Wayland backend adds no build dependencies to juce_gui_basics. JUCE talks to the compositor through its own protocol bindings and loads libwayland-client at runtime. X11 remains a supported JUCE backend. Plugin editors will continue to use X11/XWayland.

Note that this preview compiles both Wayland and X11 backends (the X11 development headers remain build dependencies at this time).

Desktop and embedded Linux

In addition to desktop Linux, embedded Linux has been an important driver for this work.

Standalone JUCE applications can now run directly on Weston without requiring an XWayland server merely to display their interface. This is useful for musical instruments, effects processors, control surfaces, kiosks, and other dedicated products built around Yocto or similarly focused Linux images. Touch input arrives directly from the compositor, so touch panels work on systems with no X server at all.

Wayland’s OpenGLContext support includes OpenGL ES and has been tested by the JUCE team on embedded hardware.

What Wayland adds over X11

The Wayland backend includes first-class desktop features such as:

  • Chinese, Japanese, and Korean (CJK) support for Input Method Editors (IMEs)
  • Smooth touchpad scrolling
  • High-resolution mouse wheels with natural scrolling
  • Compositor-driven repainting
  • Ability to run on systems without X11
  • Fractional scaling (for example 125% or 150%, per-monitor) and HiDPI support.
  • Hot-plug display support
  • File chooser integration through XDG Desktop Portal
  • Some default embedded hardware operating systems require Wayland to access OpenGL or other, similar, hardware accelerated graphics contexts

Known Limitations

Wayland is currently limited to standalone applications. Plugin editors continue to use X11/XWayland.

Other things to note:

  • WebBrowserComponent is heavily dependent upon specific X11 machinery and is therefore not available on Wayland.
  • toFront(), toBehind(), and always-on-top have no Wayland equivalent.
  • Wayland is very strict about popup/menu ordering and window placement. Wayland has no global window coordinates. A window cannot read or set its own screen position. The compositor ultimately decides where windows land. Please let us know if you see any issues here!

Known issues under investigation

  • Popup placement from hosted audio plugins
  • Drag and drop icon placement
  • Generic titlebar icons displayed

Testing

The JUCE team has tested on multiple versions of GNOME (Mutter), KDE Plasma (KWin), Hyprland, and Weston as well as on embedded hardware. Feedback from different distributions, compositors, and display configurations is very much appreciated!

Please reply to this thread with any problems you encounter. Reports are most helpful when they include:

  • Linux distribution and version
  • Desktop environment and Wayland compositor
  • Whether the application used software rendering, OpenGL, or OpenGL ES
  • Whether the problem also occurs under X11/XWayland

To compare a problem against the X11 backend on the same machine, start your app with WAYLAND_DISPLAY unset:

env -u WAYLAND_DISPLAY ./MyApp

In the rare event that your app closes suddenly, it’s likely the compositor rejecting a request and closing the connection. Run your app from a terminal with WAYLAND_DEBUG=1 and with stderr redirected to a file:

WAYLAND_DEBUG=1 ./MyApp 2> wayland.log

Please send us the last 50 lines of that log.

Usage and Development

Given the diversity of Linux-based systems we anticipate that this public preview branch will uncover a number of new issues for us to fix, on top of the limitations and known issues already listed in this thread. However, for many embedded systems without particularly complex interactive UIs, this preview branch may already be stable enough to use immediately.

7 Likes
JUCE 9.0.3 released with a public Wayland preview branch
3

This is really great. I tested Wayland APH and didn’t get any issues so far.
Is it correct, that plugins are just waiting for the settled window-embed specification for Wayland?

5

We’ve not yet decided how best to provide native Wayland plug-ins and plug-in hosting.

There is some prior precedent in the VST3 SDK and from PreSonus, but there are caveats to that approach.

At the moment we’re concentrating on the known issues with the branch, then looking at WebBrowserComponent.

2 Likes
6

One issue with plugins is that only VST3SDK has a preview of a potential implementation (taken from Fender Studio One).
So there need to be equal implementations for the other plugin formats.

Wayland doesn’t offer proper mechanisms to do this for the plugin use-case, so all the proposals are kind of “hacks” on top of what Wayland is able to do. There are several discussions on github (LV2 and CLAP repositories) that go into depth on this.

7

I’ve just pushed some changes that make it a bit easier to get started on systems that only support OpenGL ES, like the i.MX family of boards.

You can now compile the DemoRunner with just the following changes to the DemoRunner’s CMakeLists.txt:

  @@ juce_add_gui_app(DemoRunner
       NEEDS_CURL                      TRUE
  -    NEEDS_WEB_BROWSER               TRUE
  +    NEEDS_WEB_BROWSER               FALSE
  +    NEEDS_OPENGL_ES                 TRUE
  @@ target_compile_definitions(DemoRunner PRIVATE
  -    JUCE_WEB_BROWSER=1
  +    JUCE_WEB_BROWSER=0
  +    JUCE_USE_XINERAMA=0
  +    JUCE_USE_XCURSOR=0
  +    JUCE_ALSA=0

You may need to disable additional JUCE_USE_X* depending on your setup.

8

That’s great!

I’ve been encountering only one issue with popup menus. They appear much smaller on Wayland than with X11 on my machine.

I’m using Ubuntu 26.04.1 (Gnome) on a retina display, with the display scale set to 133%.

Debugging the MenuWindow with and without WAYLAND_DISPLAY reported this:

Wayland X11
baseScale 1.0 1.0
targetScale 1.33333 2.0
selfScale 2.0 2.0
scaleFactor 0.66667 1.0

Hope this helps