In practice, getting that to work in GNOME mutter required changes across the Wayland protocol layer, compositor policy, Clutter frame scheduling, KMS plane capability parsing, and the atomic commit path.

This post walks through the mutter branch that adds tearing support, wip/add-tearing-support, and explains why the final implementation is more than just setting one atomic flag.

End-to-end flow

What async page flip changes

With normal presentation, the compositor schedules a frame against the next refresh deadline and the KMS commit becomes visible on a vblank boundary. That avoids tearing, but it also means an extra wait if a fullscreen client finishes rendering just after the compositor has already targeted the current refresh.

Async page flip changes the tradeoff:

• submit the new primary plane framebuffer immediately
• let scanout switch mid-frame if needed
• reduce latency for fullscreen content that prefers it
• accept visible tearing as the tradeoff

That model only really makes sense when the content owns the whole output and is not competing with other desktop composition work.

The protocol piece: wp_tearing_control_v1

The first requirement is a way for Wayland clients to express preference. The branch adds support for the wp_tearing_control_manager_v1 protocol and a per-surface wp_tearing_control_v1 object in src/wayland/meta-wayland-tearing-control.c.

The protocol is intentionally small. Clients set one of two presentation hints:

• ASYNC if they prefer tearing for lower latency
• VSYNC if they prefer normal synchronized presentation

On the mutter side this is stored in the pending Wayland surface state as an allow_tearing bit, which then gets applied as part of normal surface state processing.

That is an important design point: the protocol does not force tearing. It only lets the client opt in.

Mutter policy: only when it is actually safe

Once the protocol state exists, mutter still needs to decide whether that hint should affect the output.

The policy in this branch is conservative:

• only a fullscreen surface can drive tearing
• the surface must be a Wayland surface
• the output must support atomic async page flip
• hardware cursor handling must not interfere

This logic lives in src/compositor/meta-compositor-view-native.c and src/backends/native/meta-onscreen-native.c.

The compositor tracks the current fullscreen actor for each stage view. If the topmost actor is a fullscreen Wayland surface, mutter checks whether that surface has tearing enabled and then requests tearing on the onscreen object. If not, it forces the output back to synchronized presentation.

That means the feature is output-scoped, but driven by the currently eligible fullscreen surface.

Async is not just a flag: frame clock changes matter

If the compositor keeps scheduling work as if presentation must align to vblank, then enabling async page flip will not buy much latency reduction.

To address that, the branch adds a new Clutter frame clock mode, CLUTTER_FRAME_CLOCK_MODE_UNLOCKED, and switches to it whenever tearing is active.

The key idea is that unlocked mode stops treating the refresh cycle as the primary scheduling constraint. Instead of pacing frames around the normal vblank deadline model, the compositor can submit work as soon as it is ready.

In the branch, meta_onscreen_native_before_redraw() updates the frame clock mode like this:

• tearing enabled -> UNLOCKED
• VRR enabled -> VARIABLE
• otherwise -> FIXED

That is one of the most important parts of the series. Without it, the kernel might accept async flips, but the compositor would still behave like a mostly vsynced system.

KMS capability plumbing: async formats are separate

A second non-obvious part is scanout format support.

Some hardware exposes a normal IN_FORMATS blob for plane formats and modifiers, but async flips may support only a subset of those combinations. This branch adds support for IN_FORMATS_ASYNC on KMS planes and stores a separate async format/modifier table per plane.

That work lives mainly in src/backends/native/meta-kms-plane.c.

Why this matters:

• a plane may be scanout-capable in general
• but not all formats or modifiers are valid for async flip
• compositor-side validation needs to know the async subset up front

Without that separation, mutter could choose a format that works for normal page flips and only discover much later that async presentation is impossible.

Output policy: cursor and direct scanout interactions

Async commits are heavily restricted in the kernel and drivers. In particular, anything beyond the primary plane update can make an async commit invalid.

This branch handles that in a few ways:

• mutter inhibits the hardware cursor when tearing is enabled
• direct scanout and fullscreen candidate selection are tied into the tearing policy
• async commits are only attempted on paths that are close to pure primary plane flips

That cursor inhibition is especially important. A cursor plane update during a tearing frame can turn what should be a simple async primary flip into a more complex atomic transaction that the driver will reject.

Making async robust: pre-test and fallback to sync

The last piece turned out to be essential in practice.

Even when a client is eligible for tearing, not every single frame is safe to submit asynchronously. During transitions you may still have plane state changes that are valid for normal commits but not for async ones.

Examples include:

• sync to async toggles
• direct scanout handoff transitions
• transient plane state changes that drivers reject for async

To make this robust, the branch adds an async pre-test in src/backends/native/meta-kms-impl-device-atomic.c:

1. build the real atomic request
2. if PAGE_FLIP_ASYNC is requested, first issue a TEST_ONLY async commit
3. if the async test fails, clear PAGE_FLIP_ASYNC
4. submit the same frame synchronously instead of hard-failing

That fallback is what makes repeated sync <-> async switching stable in practice. The compositor still prefers async when possible, but it does not get stuck on transient EINVAL failures from the atomic path.

User-facing enablement

The branch also adds an experimental mutter feature flag and settings plumbing for tearing.

The new experimental feature key is tearing in org.gnome.mutter experimental-features, and the branch also wires the state through MetaSettings so the compositor can expose and honor it consistently.

At the KMS level, mutter separately checks whether the device advertises DRM_CAP_ATOMIC_ASYNC_PAGE_FLIP before trying to use the feature.

So the effective gate is:

• feature enabled in mutter
• client opted in through tearing control
• output is fullscreen and eligible
• KMS device supports atomic async page flip

Why this series ended up larger than expected

The interesting lesson from this work is that tearing support is not really one feature. It is a chain of smaller requirements that all need to line up:

• a client protocol to express preference
• compositor policy for when that preference is honored
• a frame clock mode that does not artificially preserve vblank pacing
• async-specific plane format validation
• KMS commit handling that can fall back gracefully

Any one of those missing pieces produces a system that either does not tear when requested, tears unreliably, or falls over when the frame path changes.

Where the patches live

The mutter implementation is on this branch:

• naveenk2/mutter:wip/add-tearing-support

The main commits in the series are:

• build: Bump libdrm requirement to >= 2.4.120
• atomic: Check for atomic tearing capability
• settings: Add experimental feature for tearing
• wayland: Add support for tearing control protocol
• backends/native: Add IN_FORMATS_ASYNC and improve async (tearing) handling
• Add unlocked frame clock mode for tearing support
• kms/atomic: pre-test async and fallback to sync

Practical outcome

With this branch, mutter can finally honor a fullscreen Wayland client’s tearing hint in a way that is coherent end to end:

• the client opts in through Wayland
• mutter enables tearing only for the right surface and output state
• the frame clock stops artificially holding frames to vblank cadence
• the KMS backend uses async flips when the hardware state really supports it
• and if one frame is not async-safe, mutter falls back to sync instead of failing the presentation path

That combination is what makes tearing support usable rather than merely present.

On a 40-120 Hz VRR panel I noticed unmistakable judder when playing 24 fps content in mpv on Wayland. 50 fps content looked fine. This post walks through how the problem manifests in the KMS layer, what the missing piece is, and how a small Wayland protocol plus a low-frame-cadence path in mutter fix it.

What judder looks like in the KMS log

mutter has a debug topic that logs the last four observed present intervals per CRTC. With MUTTER_DEBUG_TOPICS=kms enabled, playing the 24 fps clip on the unpatched stack produces lines like:

KMS_DEADLINE: CRTC 149 VRR present intervals { 8333, 16667, 8333, 16667 }  → min 8333 µs
KMS_DEADLINE: CRTC 149 VRR present intervals { 16667, 8333, 16667, 16667 } → min 8333 µs
KMS_DEADLINE: CRTC 149 VRR present intervals { 33332, 16669, 16663, 16670 } → min 16663 µs
KMS_DEADLINE: CRTC 149 VRR present intervals { 16664, 33333, 16671, 16663 } → min 16663 µs
KMS_DEADLINE: CRTC 149 VRR present intervals { 25002, 24999, 25001, 16664 } → min 16664 µs

Those are scanout intervals in microseconds. 8333 µs is 120 Hz, 16667 µs is 60 Hz, 25000 µs is 40 Hz, 33333 µs is 30 Hz. For 23.976 fps content the nominal frame interval is 41 708 µs, but the actual presents wander all over the 40–120 Hz VRR window.

That wander is exactly what the eye picks up as judder. Each video frame is held for an arbitrary number of scanout periods until the next frame is ready, and the period itself is not stable.

Why the compositor can’t fix this on its own

VRR works in the direction of latency: as soon as a frame arrives, scan it out. The panel firmware also enforces a minimum refresh rate (40 Hz here) by re-sending the last line when nothing has arrived in a while. So at 24 fps, between two real frames there is always at least one self-refresh from the panel — and the exact moment it happens depends on when the compositor’s frame clock decides to wake up. The compositor has no idea the client intends to post frames at a fixed 23.976 Hz cadence, so it cannot align anything.

The fix is to tell the compositor what cadence the client is producing.

The content-frame-rate-v1 protocol

A new Wayland protocol, wp_content_frame_rate_v1, lets a client attach a rational frame rate (numerator / denominator) to a surface. The compositor is free to use that hint to schedule its frame clock and, more importantly, to retune the panel.

Three components needed changes:

1. wayland-protocols – the XML for the protocol.
2. mpv – bind the manager, create a per-surface object, and call set_frame_rate whenever the video track’s container FPS changes.
3. mutter – receive the hint, plumb it from the Wayland surface state into MetaOnscreenNative, and compute a virtual refresh mode for the CRTC.

The mutter side is where the interesting logic lives.

Low Frame Cadence in mutter

When VRR is on and the client supplies a content frame rate, mutter computes:

content_fps = numerator / denominator
vrr_min_hz  = 1_000_000 / max_refresh_interval_us
N           = max(ceil(vrr_min_hz / content_fps), 1)
target_hz   = content_fps * N

N is the smallest integer multiplier that brings the content rate up to (or above) the panel’s VRR floor. If the resulting target_hz lies within [vrr_min, vrr_max], mutter clones the current KMS mode and rewrites vtotal, vsync_start, vsync_end, and vrefresh so that the panel scans out at exactly target_hz. From that point on every video frame is displayed for N scanout periods of fixed length.

For the two cases tested:

The N=2 row is the actual fix for the judder I started with.

Tracing the patched stack

To verify each link of the chain I added MP_VERBOSE logs in mpv and meta_topic(META_DEBUG_KMS, ...) / META_DEBUG_WAYLAND logs in mutter. Then I played the same 23.976 fps clip:

mpv (-v plus WAYLAND_DEBUG=1):

-> wl_registry#2.bind(38, "wp_content_frame_rate_manager_v1", 1, new id #29)
-> wp_content_frame_rate_manager_v1#29.get_surface_content_frame_rate(..., wl_surface#5)
-> wp_content_frame_rate_v1#39.set_frame_rate(24000, 1001)

mutter (MUTTER_DEBUG_TOPICS=wayland,kms, captured from the journal):

content-frame-rate: surface=5 set_frame_rate 24000/1001 (23.976 fps)
KMS: LFC virtual refresh target 47.952 Hz (content 24000/1001, N=2)
KMS: Setting CRTC (149) virtual refresh mode to 47.952 Hz
KMS: [atomic] Setting CRTC 149 (/dev/dri/card1) property 'VRR_ENABLED' to 1

And, the payoff, the KMS deadline topic after the mode switch settles:

KMS_DEADLINE: CRTC 149 VRR present intervals { 20829, 20834, 20836, 20838 }  → min 20829 µs
KMS_DEADLINE: CRTC 149 VRR present intervals { 20834, 20833, 20838, 20829 }  → min 20829 µs
KMS_DEADLINE: CRTC 149 VRR present intervals { 20833, 20838, 20829, 20834 }  → min 20829 µs

Every present interval is within ±5 µs of 20 833 µs, which is exactly half the 24 fps frame interval. The panel is now scanning out at a perfectly steady 47.952 Hz and the player is delivering one new frame every other scanout.

For the 49.984 fps clip the equivalent capture shows the panel locked at ~50 Hz (20 000 µs ±10 µs) for the entire playback window.

Lifecycle

Closing mpv between clips emits the expected teardown:

KMS: [atomic] Setting CRTC 149 ... property 'VRR_ENABLED' to 0

Opening the next clip re-establishes the hint and re-enables VRR + virtual mode with whatever new N is appropriate for the new content rate. No manual configuration, no user-visible mode change.

Visual result

Judder is gone for the 24 fps case. The 50 fps case, which was already acceptable, now scans out at exactly the content rate rather than relying on whatever cadence the frame clock happened to converge to. Cursor movement and desktop animations remain VRR (they’re driven by the regular frame clock, which is what the MODE_VARIABLE clutter mode is for).

Where the patches live

• wayland-protocols XML – 0001-add-content-frame-rate-protocol-v1.patch
• mpv – video/out/wayland_common.c, player/misc.c, video/out/vo.h
• mutter – src/wayland/meta-wayland-content-frame-rate.c, plumbing through meta-wayland-surface.c, and the LFC path in src/backends/native/meta-onscreen-native.c plus src/backends/native/meta-crtc-kms.c / meta-kms-mode.c

If you have a wide-range VRR panel and a low-fps clip handy, the same logging above is enough to confirm the chain end to end on your own setup.