Splitting up the Frame Clock

Readers be advised, this is somewhat of a deep dive into the guts of Mutter. With that out in the open, lets start!

Not too long ago mutter saw amerge request land, that has one major aim: split up the frame clock so that when using the Wayland session, each CRTC is driven by its own frame clock. In effect the goal here is that e.g. a 144 Hz monitor and a 60 Hz monitor being active in the same session will not have to wait for each other to update, and that the space they occupy on the screen will draw at their own pace. A window on the 144 Hz monitor will paint at 144 Hz, and mutter will composite to the monitor at 144 Hz, while a window on the 60 Hz monitor will paint at 60 Hz and Mutter will composite to the monitor at 60 Hz.

All of this is roughly achieved by the changes summarized below.

Preface

In the beginning of times, Clutter was an application toolkit. As such, it assumed (1) the existence of a window compositor, and (2) the compositor is a different process. Back then, Wayland was still in its early infancy, and those assumptions wouldn’t conflict with writing a X11 window manager. After all, a X11 window manager is pretty much just another client application.

Over time, however, Clutter started to grow Wayland integration in itself. Deeper and deeper surgeries were made to it to accomodate it being used by a Wayland compositor.

In 2016, the Cogl and Clutter codebases were merged with Mutter codebase, and they all live in the same repository now. However, to this day, relics from the time when Clutter was an application toolkit are still present in Mutter’s Clutter. One such relic is ClutterMasterClock .

ClutterMasterClock

ClutterMasterClock was the main frame clock that drove Clutter painting. As an application toolkit, only a single, global frame clock was necessary; but as a compositor toolkit, this design doesn’t fit the requirements for multi-monitor setups.

Over the last cycles, there has been some attempts to make it handle multiple monitors slightly better by juggling multiple monitor with their own refresh rates and CRTC clocks using various tricks, but the fundamental design was standing in the way for making substantial progress, so it has been completely decommissioned.

Enters ClutterFrameClock .

ClutterFrameClock is the new frame clock object that aims to drive a single “output”. Right now, it has a fixed refresh rate, and a single “frame listener” and “presenter” notifying about frames being presented. It is also possible to have multiple frame clocks running in parallel.

However, ClutterFrameClock alone isn’t enough to achieve independence of monitor redraws.

Stage Views

Mutter has a single stage that covers the union of all monitor rectangles. But how does it render different contents to each one of them?

That’s one of the main responsibilities of ClutterStageView .

ClutterStageView was the answer to the need of drawing the stage at different framebuffers. ClutterStageView corresponds roughly to one monitor. Each ClutterStageView holds the on-screen framebuffer that the monitor displays; if using shadow framebuffers, ClutterStageView also handles them; and finally, it also handles the monitor rotation.

Now, ClutterStageView also handles the monitor’s frame clock. By handling the frame clock, each view is also responsible of notifying about frames being presented, and handling the frame clock dispatching

The frame scheduling related logic (including flip counting, schedule time calculation, etc) was spread out in ClutterMasterClockDefault , ClutterStage , ClutterStageCogl , MetaRendererNative , MetaStageNative , and MetaStageX11 , but has now now been concentrated to ClutterFrameClock and ClutterStageView alone.

Actors, Actors Everywhere

When animating interface elements, the core object that does that is ClutterTimeline and its subclass, ClutterTransition .

Timelines and transitions saw frames whenever the master clock ticked. With the master now clock gone, they need to find an appropriate frame clock to drive them. In most (and after this change effectively all) cases a timeline was used to directly drive an animation related to an actor. This indirect relationship is now made explicit, and the timeline uses the actor to find what stage view it is being displayed on, and with that information, picks an appropriate frame clock to attach to.

For transitions, used extensively by GNOME Shell to implement animations, this is handled by making a ClutterAnimatable provide the actor, and for stand-alone timelines, it’s a property set directly on the timeline before it’s started.

This means that when an actor moves across the stage and enters a different stage view, the timeline will be notified about this and will decide whether to migrate to a different frame clock.

What About X11?

In the X11 session, we composite the whole X11 screen at once, without any separation between monitors. This remains unchanged, with the difference being where scheduling takes place (as mentioned in an earlier point). The improvements described here are thus limited to using the Wayland session.

Be aware of API changes

This is quite a substantial change in how painting works in mutter, API changes could not be avoided. With that in mind, the changes needed are small , and mostly handled transparently by GNOME Shell itself. In fact, in all of GNOME Shell’s Javascript code, only two places needed change.

To be specific, for extension developers, there are two things to keep in mind:

• If you use a St.Adjustment . You must now pass an actor when constructing it. This actor will determine what frame clock will drive the adjustment.
• Some signals saw their type signatures change, namely ClutterStage::presented , ClutterStage::after-paint .

Final Thoughts

This is a big achievement to Mutter, GNOME Shell, its users, and especially to the contributors that were part of this. The road to reach this point was long and tortuous, and required coordinated efforts of dozens of contributors over the course of at least 5 years. We’d like to take a moment to appreciate this milestone and congratulate each and every single contributor that was part of this. Thank you so much!