Martin Stransky's Blog – Firefox hacking in Fedora

Firefox & Linux in 2025

HDR YouTube video clip I used for testing

Last year brought a wealth of new features and fixes to Firefox on Linux. Besides numerous improvements and bug fixes, I want to highlight some major achievements: HDR video playback support, reworked rendering for fractionally scaled displays, and asynchronous rendering implementation. All this progress was enabled by advances in the Wayland compositor ecosystem, with new features implemented by Mutter and KWin.

HDR

The most significant news on the Wayland scene is HDR support, tracked by Bug 1642854. It’s disabled by default but can be enabled in recent Wayland compositors using the gfx.wayland.hdr preference at about:config (or by gfx.wayland.hdr.force-enabled if you don’t have an HDR display).

HDR mode uses a completely different rendering path, similar to the rendering used on Windows and macOS. It’s called native rendering or composited rendering, and it places specific application layers directly into the Wayland compositor as subsurfaces.

The first implementation was done by Robert Mader (presented at FOSDEM), and I unified the implementation for HDR and non-HDR rendering paths as new WaylandSurface object.

The Firefox application window is actually composited from multiple subsurfaces layered together. This design allows HDR content like video frames to be sent directly to the screen while the rest of the application (controls and HTML page) remains in SDR mode. It also enables power-efficient rendering when video frames are decoded on the graphics card and sent directly to the screen (zero-copy playback). In fullscreen mode, this rendering is similar to mpv or mplayer playback and uses minimal power resources.

I also received valuable feedback from AMD engineers who suggested various improvements to HDR playback. We removed unnecessary texture creation over decoded video frames (they’re now displayed directly as wl_buffers without any GL operations) and implemented wl_buffer recycling as mpv does.

For HDR itself (since composited rendering is available for any video playback), Firefox on Wayland uses the color-management-v1 protocol to display HDR content on screen, along with BT.2020 video color space and PQ color transfer function. It uses 10-bit color vectors, so you need VP9 version 2 to decode it in hardware. Firefox also implements software decoding and direct upload to dmabuf frames as a fallback.

The basic HDR rendering implementation is complete, and we’re now in the testing and bug-fixing phase. Layered rendering is quite tricky as it involves rapid wl_surface mapping/unmapping and quick wl_buffer switches, which are difficult to handle properly. HDR rendering of scaled surfaces is still missing—we need fractional-scale-v2 for this (see below), which allows positioning scaled subsurfaces directly in device pixels. We also need to test composited/layered rendering for regular web page rendering to ensure it doesn’t drain your battery. You’re very welcome to test it and report any bugs you find.

Fractional scale

The next major work was done for fractional scale rendering, which shipped in Firefox 147.0. We updated the rendering pipeline and widget sizing to support fractionally scaled displays (scales like 125%, etc.). This required reworking the widget size code to strictly upscale window/surface sizes and coordinates and never downscale them, as downscaling introduces rounding errors.

Another step was identifying the correct rounding algorithm for Wayland subsurfaces and implementing it. Wayland doesn’t define rounding for it, only for toplevel windows, so we’re in a gray area here. I was directed to Stable rounding by Michel Daenzer. It’s used by Mutter and Sway so Firefox implements it for those two compositors while using a different implementation for KWin. This may be updated to use the fractional-scale-v2 protocol when it becomes available.

Fractional scaling is enabled by default, and you should see crisp and clear output regardless of your desktop environment or screen scale.

Asynchronous rendering

Historically, Firefox disabled and re-enabled the rendering pipeline for scale changes, window create/destroy events, and hide/show sequences. This stems from Wayland’s architecture, where a Wayland surface is deleted when a window becomes invisible or is submitted to the compositor with mismatched size/scale (e.g., 111 pixels wide at 200% scale).

Such rendering disruptions cause issues with multi-threaded rendering—they need to be synchronized among threads, and we must ensure surfaces with the wrong scale aren’t sent to the screen, as this leads to application crashes due to protocol errors.

Firefox 149.0 (recent nightly) has a reworked Wayland painting pipeline (Bug 1739232) for both EGL and software rendering. Scale management was moved from wl_buffer fixed scale to wp_viewport, which doesn’t cause protocol errors when size/scale doesn’t match (producing only blurred output instead of crashes).

We also use a clever technique: the rendering wl_surface / wl_buffer / EGLWindow is created right after window creation and before it’s shown, allowing us to paint to it offscreen. When a window becomes visible, we only attach the wl_surface as a subsurface (making it visible) and remove the attachment when it’s hidden. This allows us to keep painting and updating the backbuffer regardless of the actual window status, and the synchronized calls can be removed.

This brings speed improvements when windows are opened and closed, and Linux rendering is now synchronized with the Windows and macOS implementations.

… and more

Other improvements include a screen lock update for audio playback, which allows the screen to dim but prevents sleep when audio is playing. We also added asynchronous Wayland object management to ensure we cleanly remove Wayland objects without pending callbacks, along with various stability fixes.

And there are even more challenges waiting for us Firefox Linux hackers:

Wayland session restore (session-restore-v1) to restore Firefox windows to the correct workspace and position.
Implement drag and drop for the Firefox main window, and possibly add a custom Wayland drag and drop handler to avoid Gtk3 limitations and race conditions.
Utilize the fractional-scale-v2 protocol when it becomes available.
Investigate using xdg-positioner directly instead of Gtk3 widget positioning to better handle popups.
Vulkan video support via the ffmpeg decoder to enable hardware decoding on NVIDIA hardware.

And of course, we should plan properly before we even start. Ready, Scrum, Go!

Firefox 124 supports GNOME titlebar actions

On GNOME Firefox runs with disabled system titlebar by default. It saves horizontal space on wide screens but also removes control over window, traditionally provided by Window manager and desktop environment.

GNOME allows to set titlebar actions by gnome-tweaks tool, you can define window actions for double click by first mouse button, middle click and secondary button. These choices are not followed by Firefox if system titlebar is off because Firefox integrates titlebar with browser tab strip and performs build-in tasks like open/close new tab or toggle maximize.

However Firefox 124 improves it and follows mouse button double click action defined by GNOME so you change it as you wish.

You also can define titlebar action for middle mouse button click, which opens a new tab by default. Set widget.gtk.titlebar-action-middle-click-enabled at about:config and it should work then.

Wayland proxy load balancer

Updated Dec 23

Wayland clients (applications) may face various difficulties not primary caused by them. There are three main Wayland compositors (Mutter/Gnome, KWin/KDE and WLRoots/Sway) and every compositor behaves differently in some corner cases not exactly defined by Wayland standards (or bents the specification somehow).

In X11 world an underlying X.Org implementation is the same for every desktop environment and there are differences introduced by window managers. Wayland merged window manager (like Metacity) and renderer (X11) to one block.

One of Firefox Wayland top crash bug is a Lost connection to Wayland compositor one.

Mutter (and maybe other ones) terminates Wayland client if it’s recognized as stalled. It usually means Wayland client doesn’t read messages from Wayland display socket fast enough and compositor message output buffer is full. It may be a bug in application itself (an event loop is not processed) or it’s caused by input devices like 1000 Hz mouse which generates too many events.

Unfortunately Wayland protocol doesn’t implement any kind of display connection management. Once the connection is lost / disconnected, there isn’t any way how it can be restored and Wayland client is terminated. The most visible example is Wayland compositor crash which takes down all applications, there isn’t any recovery point available.

There are various discussions going on [1],[2] but they’re stalled too 😀 as well as discussion about PIP – Picture-in-Picture Wayland protocol extension implementation [3].

But Firefox needs to solve the crashes caused by message jam right now as it’s shipped to wide audience. An initial idea popped out in discussion to create a proxy between Firefox and Wayland compositor to cache messages and prevent compositor message queue overflow. It’s very simplified case of WayPipe which routes Wayland communication over network and adds network transparency to Wayland protocol.

There’s initial successful proof-of-concept written in Rust and I implement it in C++ as wayland-proxy module which can be shipped with Firefox (mainly because my Rust knowledge is non-existent).

Wayland-proxy can be used as stand alone application or library included in Wayland application and it’s shipped with Fedora Firefox 121.0 right now and let’s see how it works.

UPDATE: Thanks to the valuable feedback at comments, it’s definitely worth to looks at it! There are more issues which needs different approach and Firefox problem also depends on Gtk3 and it’s way of handling Wayland connection. I was also pointed to Qt 6.6 robustness project which implement Wayland reconnection on Qt toolkit level.

Mozilla ships Firefox 121.0 with Wayland enabled

Wayland pub at Brno city — Even my hometown Brno has its own Wayland 😀

Firefox on Linux hit another milestone as Mozilla defaults to Wayland backend instead of XWayland X11 emulation in Firefox 121. It’s a logic step as XWayland emulation introduces bugs from both Wayland and X11 worlds together so better run Wayland directly.

As Fedora has provided Firefox on Wayland backend for years, this change affects mainly Ubuntu and its Firefox/Snap users (if Canonical decides to follow Mozilla here), Firefox shipped as Flatpak and next Firefox ESR and Thunderbird releases.

And what to expect? Beside all the goodies I need to mention Wayland differences and regressions from X11.

Wayland doesn’t allow applications to position itself on desktop and it can’t place itself on a particular workspace.

It means Firefox session restore feature works differently on Wayland and all Firefox windows are restored on first workspace.
Wayland client can’t place itself on top, above of other clients, which is another Wayland security feature. It affects Firefox Picture-in-Picture (PIP) windows, they can’t be placed on top by Firefox itself.

You need to guide Wayland compositor to keep it there. Fortunately a GNOME extension may be installed for it and KDE allows to create a window rule.

Or you can click by right mouse button on PIP window and select ‘Always on Top’ option there.

There’s ongoing discussion about universal PIP Window interface as Wayland protocol extension (similar to PIP on Android) but we’re far from general agreement here.

And if you feel Wayland is too restrictive for you while it’s missing any benefit it can be disabled in Firefox by MOZ_ENABLE_WAYLAND env variable. Just add

export MOZ_ENABLE_WAYLAND=0

line at .bashrc file (or similar one for different shell) or run Firefox from terminal as

MOZ_ENABLE_WAYLAND=0 firefox

or add it to /usr/bin/firefox launch script.

Q3 Firefox Linux update

Let’s highlight some updates of Firefox development from Linux perspective for last three months.

Wayland backend is gaining momentum at Mozilla upstream. It’s enabled by default in Fedora/Arch Linux but Mozilla is a bit hesitant and runs Wayland for Nightly/Beta only. Mozilla official binaries, Ubuntu/Snap and Mozilla/flatpak switches to XWayland mainly due to missing test coverage of Wayland builds.

But Mozilla migrates its testsuite to Ubuntu 22.04 which also involves Wayland testing (Bug 1813588) so let’s hope we see Wayland in release soon (Bug 1752398). Indeed there are still some Wayland bugs to fix and we keep an eye on it.

Dbus-glib is no longer needed by Firefox to build. This old dependency from Gtk2 times was removed in Firefox 120.0 where we switch to Gio DBus interface and async implementation based on MozPromise. Dbus-glib can be removed from build roots for good and that helps mainly to flatpak packaging.

Kiosk mode has a new feature – with ‘–kiosk-monitor’ parameter you can place Firefox kiosk window to a specified monitor. That supports Wayland/kiosk environments and mutihead setup where one box covers more displays. We also switch to fullscreen immediately after Firefox start to make sure we reliably cover whole screen in kiosk mode.

Idle monitor/service was implemented by org.gnome.Mutter.IdleMonitor DBus interface. Former X11 version crashes and doesn’t work on Wayland. I may look at KDE/Sway interfaces too.

I also investigated broken Gnome Shell search service in Fedora and found out that Firefox DBus search interface needs to be ‘Activatable’. That involves to implement org.freedesktop.Application DBus interface, ships corresponding service file at /usr/share/dbus-1/services/ and has application desktop file in correct format (org.mozilla.firefox.desktop instead of recent Fedora plain firefox.desktop).

So I renamed Fedora Firefox desktop file to org.mozilla.firefox.desktop and bundled DBus service search file and everything looked okay except … Gnome Shell default launcher has hardcoded ‘firefox.desktop‘ so Firefox was removed from default applications :D. Well, desktop file change is allowed for new releases only. Lesson learned.

But there’s a way. You can use plain firefox.desktop name but you need a binary service launcher at /usr/share/dbus-1/services/ file so DBus can run the service on demand. As we don’t want to run Firefox for every Gnome search I put simple ‘/usr/bin/false’ there and oala! Search works and Firefox is still in Gnome taskbar.

But, well, desktop is not just a Gnome. KDE/Plasma has also a vote and just can’t stand such level hack and simply crashed. I don’t blame it, non-canonical desktop file name with DBusActivatable flag may be too much for poor launcher. Nobody is perfect.

So right now we have broken Gnome search provider but I know where the problem is and look forward to fix it for Fedora 40, with desktop file rename and implementation of org.freedesktop.Application DBus interface.

And that’s all for Q3, let’s see next quarter.