Skip to content

backends/native: Add support for variable refresh rate

Dor Askayo requested to merge doraskayo/mutter:vrr-support into main


There are a few small design decisions to make, but overall the core VRR experience is quite good in my tests.

Setting the variable-refresh-rate experimental feature is required to enable the feature, followed by a restart of the session (log out and back in):

$ gsettings set org.gnome.mutter experimental-features "['variable-refresh-rate']"

There are some limitations still, but those are out of scope for this MR and covered in the Caveats section.


  • Extensively test using VRRTest. (
  • Test heavy OpenGL apps.
  • Test heavy Vulkan apps.
  • Test an "extend" multi-monitor configuration which combines VRR and non-VRR monitors.
  • Test a "mirror" multi-monitor configuration which combines VRR and non-VRR monitors.
  • Test clients that use subsurfaces.
  • Test clients that use the presentation-time protocol.


This MR adds the logic required to detect monitors that are capable of VRR and the ability to activate it using KMS properties.

It also adds the ability to enable or disable VRR on capable monitors using the DisplayConfig DBus API, and makes this configuration persist via monitors.xml.

Finally, once configured to be enabled, VRR is actually activated on a monitor when a window that supports it covers the entire monitor on the visible workspace, doesn't have any transitions or animations, and isn't covered by any shell UI elements.


Stutter in Cursor Movement with Passively Updating Fullscreen Clients

As a limitation of the atomic KMS API, it's not possible to update the cursor position more often than the display content. This means that when VRR is enabled and a client update rate is very low (such as a fullscreen Terminal window), the cursor position would similarly update less frequently.

As a partial workaround, this MR guarantees that the cursor update rate would be no less than 30 Hz. This limitation is set below most VRR refresh rate ranges to avoid negatively impacting the VRR effect due to cursor movement.

30 Hz is still a rather low update rate however, and can appear stuttery to some. A higher minimum update rate can be considered based on user feedback.

Missing Wayland Protocol

Support for VRR isn't advertised by Wayland (and Xwayland) clients at the moment since there is no Wayland protocol which allows it to be advertised. (wayland/wayland/issues/84) There are also alternative solutions being proposed. (

For now, it is assumed that every Wayland and X11 window supports VRR. This means that applications which have compatibility issues with VRR may behave poorly while it's active.

Related MRs


  • !3080 (merged) – fixes an issue in Mutter's direct scanout path that could result in severe stutter and missed frames, which significantly impacted VRR in my tests.
  • !3085 (merged) – required to avoid a crash with the addition of the variable-refresh-rate experimental feature.
  • !3549 (merged) – required to avoid stutter with Firefox (Wayland).
  • !3521 (merged) – required to avoid a degradation following !3549 (merged).
  • !3560 (merged) – required to handle a frame scheduling edge case better.
  • !3561 (merged) – required to handle a frame scheduling edge case better.
Edited by Dor Askayo

Merge request reports