linuxmint · mtwebster · Mar 2, 2026 · Feb 27, 2026
diff --git a/js/ui/appSwitcher/appSwitcher3D.js b/js/ui/appSwitcher/appSwitcher3D.js
@@ -21,7 +21,7 @@ const PREVIEW_SCALE = 0.5;
 const TITLE_POSITION = 7/8; // percent position
 var ANIMATION_TIME = 250; // ms
 const SWITCH_TIME_DELAY = 100; // milliseconds
-const DIM_FACTOR = 0.4; // percent
+const DIM_OPACITY = 102;
 
 function AppSwitcher3D() {
     this._init.apply(this, arguments);
@@ -37,11 +37,7 @@ AppSwitcher3D.prototype = {
         this._icon = null;
         this._lastTime = 0;
 
-        if (!Meta.is_wayland_compositor()) {
-            this._background = Meta.X11BackgroundActor.new_for_display(global.display);
-        } else {
-            this._background = new Clutter.Actor();
-        }
+        this._background = Main.createFullScreenBackground();
 
         this._background.hide();
         global.overlay_group.add_actor(this._background);
@@ -75,7 +71,7 @@ AppSwitcher3D.prototype = {
         Main.panelManager.panels.forEach(function(panel) { panel.actor.set_reactive(false); });
 
         this._background.ease({
-            dim_factor: DIM_FACTOR,
+            opacity: DIM_OPACITY,
             duration: ANIMATION_TIME,
             mode: Clutter.AnimationMode.EASE_OUT_QUAD
         });
@@ -140,7 +136,7 @@ AppSwitcher3D.prototype = {
         // background
         this._background.remove_all_transitions();
         this._background.ease({
-            dim_factor: 1.0,
+            opacity: 255,
             duration: ANIMATION_TIME,
             mode: Clutter.AnimationMode.EASE_OUT_QUAD,
             onComplete: () => this._destroyActors()

diff --git a/js/ui/backgroundManager.js b/js/ui/backgroundManager.js
@@ -34,20 +34,14 @@ var BackgroundManager = class {
     }
 
     showBackground() {
-        if (Meta.is_wayland_compositor()) {
-            global.bottom_window_group.show();
-        }
-        else {
-            global.background_actor.show();
+        for (let actor of global.get_background_actors()) {
+            actor.show();
         }
     }
 
     hideBackground() {
-        if (Meta.is_wayland_compositor()) {
-            global.bottom_window_group.hide();
-        }
-        else {
-            global.background_actor.hide();
+        for (let actor of global.get_background_actors()) {
+            actor.hide();
         }
     }
 

diff --git a/js/ui/expo.js b/js/ui/expo.js
@@ -38,12 +38,7 @@ Expo.prototype = {
         // one. Instances of this class share a single CoglTexture behind the
         // scenes which allows us to show the background with different
         // rendering options without duplicating the texture data.
-        if (!Meta.is_wayland_compositor()) {
-            this._background = Meta.X11BackgroundActor.new_for_display(global.display);
-        } else {
-            this._background = new Clutter.Actor();
-        }
-
+        this._background = Main.createFullScreenBackground();
         this._background.hide();
         global.overlay_group.add_actor(this._background);
 
@@ -349,13 +344,6 @@ Expo.prototype = {
         this._gradient.show();
         Main.panelManager.disablePanels();
 
-        this._background.dim_factor = 1;
-        this._background.ease({
-            dim_factor: 0.4,
-            duration: Main.animations_enabled ? ANIMATION_TIME : 0,
-            mode: Clutter.AnimationMode.EASE_OUT_QUAD
-        });
-
         activeWorkspace.setOverviewMode(true);
 
         this._coverPane.raise_top();

diff --git a/js/ui/expoThumbnail.js b/js/ui/expoThumbnail.js
@@ -390,10 +390,8 @@
         this.background = new Clutter.Group();
         this.contents.add_actor(this.background);
 
-        if (!Meta.is_wayland_compositor()) {
-            let desktopBackground = Meta.X11BackgroundActor.new_for_display(global.display);
-            this.background.add_actor(desktopBackground);
-        }
+        let desktopBackground = Main.createFullScreenBackground();
+        this.background.add_actor(desktopBackground);
 
         let backgroundShade = new St.Bin({style_class: 'workspace-overview-background-shade'});
         this.background.add_actor(backgroundShade);
@@ -817,10 +815,10 @@
                window.showUrgencyState();
                if (row == nRows)
                    offset = lastRowOffset;
                let [wWidth, wHeight] = [window.realWindow.width, window.realWindow.height];
                let scale = Math.min(1, maxWindowWidth / wWidth, maxWindowHeight / wHeight);
                let x = monitor.x + offset + (spacing * col) + (maxWindowWidth * (col - 1)) + ((maxWindowWidth - (wWidth * scale)) / 2);
                let y = monitor.y + (spacing * row) + (maxWindowHeight * (row - 1)) + ((maxWindowHeight - (wHeight * scale)) / 2);

                window.icon.raise_top();
                // all icons should be the same size!

diff --git a/js/ui/main.js b/js/ui/main.js
@@ -672,6 +672,32 @@ function getPanels() {
     return panelManager.getPanels();
 }
 
+/**
+ * createFullScreenBackground:
+ *
+ * Creates a full-stage background actor containing one background per monitor.
+ * On X11, each child is the root pixmap actor positioned at the monitor's
+ * location. On Wayland, each child is a clone of the layer-shell background
+ * surface for that monitor.
+ *
+ * Returns: a ClutterActor covering all monitors
+ */
+function createFullScreenBackground() {
+    let container = new imports.gi.Clutter.Actor();
+
+    for (let i = 0; i < layoutManager.monitors.length; i++) {
+        let monitor = layoutManager.monitors[i];
+        let bg = Meta.create_background_for_monitor(global.display, i);
+        if (bg) {
+            bg.set_position(monitor.x, monitor.y);
+            bg.set_size(monitor.width, monitor.height);
+            container.add_child(bg);
+        }
+    }
+
+    return container;
+}
+
 let _workspaces = [];
 let _checkWorkspacesId = 0;
 

diff --git a/js/ui/overrides.js b/js/ui/overrides.js
@@ -127,13 +127,13 @@ function overrideClutter() {
 }
 
 function overrideMeta() {
-    Meta.BackgroundActor.new_for_screen = function(screen) {
-        if (!Meta.is_wayland_compositor()) {
-            return Meta.X11BackgroundActor.new_for_display(global.display);
-        } else {
-            return new Clutter.Actor();
+    Meta.BackgroundActor = {
+        new_for_screen: function(_screen) {
+            logError("Meta.BackgroundActor.new_for_screen() is deprecated, use Meta.create_background_for_monitor() or Main.createFullScreenBackground().");
+            return Meta.X11BackgroundActor.new_for_display(global.display) ||
+                   new Clutter.Actor();
         }
-    }
+    };
 
     Meta.disable_unredirect_for_screen = function(screen) {
         Meta.disable_unredirect_for_display(global.display);

diff --git a/js/ui/overview.js b/js/ui/overview.js
@@ -247,19 +247,10 @@ Overview.prototype = {
         // one. Instances of this class share a single CoglTexture behind the
         // scenes which allows us to show the background with different
         // rendering options without duplicating the texture data.
-        this._background = new Clutter.Actor();
+        this._background = Main.createFullScreenBackground();
         this._background.set_position(0, 0);
         this._group.add_actor(this._background);
 
-        let desktopBackground;
-        if (!Meta.is_wayland_compositor()) {
-            desktopBackground = Meta.X11BackgroundActor.new_for_display(global.display);
-        } else {
-            desktopBackground = new Clutter.Actor();
-        }
-
-        this._background.add_actor(desktopBackground);
-
         let backgroundShade = new St.Bin({style_class: 'workspace-overview-background-shade'});
         backgroundShade.set_size(global.screen_width, global.screen_height);
         this._background.add_actor(backgroundShade);

diff --git a/js/ui/screensaver/screenShield.js b/js/ui/screensaver/screenShield.js
@@ -1164,23 +1164,13 @@ var ScreenShield = GObject.registerClass({
     _createBackgrounds() {
         this._destroyBackgrounds();
 
-        if (Meta.is_wayland_compositor()) {
-            // TODO: Waiting on:
-            //   muffin: https://github.com/linuxmint/muffin/pull/784
-            //   cinnamon-settings-daemon: https://github.com/linuxmint/cinnamon-settings-daemon/pull/437
-            // 
-            // Once those are merged we can access the layer-shell surfaces of csd-background and avoid
-            // having to load them in Cinnamon.
-            //
-            // For now, there is only a black background for the screensaver.
-            return;
-        }
-
         let nMonitors = Main.layoutManager.monitors.length;
 
         for (let i = 0; i < nMonitors; i++) {
             let monitor = Main.layoutManager.monitors[i];
-            let background = Meta.X11BackgroundActor.new_for_display(global.display);
+            let background = Meta.create_background_for_monitor(global.display, i);
+            if (!background)
+                continue;
 
             background.reactive = false;
 

diff --git a/src/cinnamon-global.c b/src/cinnamon-global.c
@@ -9,7 +9,6 @@
 #include <meta/meta-x11-display.h>
 #include <meta/compositor-muffin.h>
 #include <meta/meta-cursor-tracker.h>
-#include <meta/meta-background-actor.h>
 #include <meta/meta-settings.h>
 #include <meta/meta-backend.h>
 #include <meta/util.h>
@@ -145,6 +144,8 @@ cinnamon_global_get_property(GObject         *object,
       g_value_set_object (value, meta_get_top_window_group_for_display (global->meta_display));
       break;
     case PROP_BACKGROUND_ACTOR:
+      g_warning_once ("global.background_actor is deprecated and X11-only. "
+                      "Use global.get_background_actors() instead.");
       g_value_set_object (value, meta_get_x11_background_actor_for_display (global->meta_display));
       break;
     case PROP_DESKLET_CONTAINER:
@@ -392,9 +393,9 @@ cinnamon_global_class_init (CinnamonGlobalClass *klass)
                                    PROP_BACKGROUND_ACTOR,
                                    g_param_spec_object ("background-actor",
                                                         "Background Actor",
-                                                        "Actor drawing root window background",
+                                                        "Actor drawing root window background (X11 only, deprecated)",
                                                         CLUTTER_TYPE_ACTOR,
-                                                        G_PARAM_READABLE));
+                                                        G_PARAM_READABLE | G_PARAM_DEPRECATED));
   g_object_class_install_property (gobject_class,
                                    PROP_DESKLET_CONTAINER,
                                    g_param_spec_object ("desklet-container",
@@ -760,6 +761,23 @@ cinnamon_global_get_window_actors (CinnamonGlobal *global)
   return meta_get_window_actors (global->meta_display);
 }
 
+/**
+ * cinnamon_global_get_background_actors:
+ *
+ * Gets the list of per-monitor background actors created by
+ * meta_create_background_for_monitor(). These are the live actors in the
+ * scene graph and can have effects applied to them directly.
+ *
+ * Return value: (element-type Clutter.Actor) (transfer none): the list of background actors
+ */
+GList *
+cinnamon_global_get_background_actors (CinnamonGlobal *global)
+{
+  g_return_val_if_fail (CINNAMON_IS_GLOBAL (global), NULL);
+
+  return meta_get_background_actors_for_display (global->meta_display);
+}
+
 static void
 global_stage_notify_width (GObject    *gobject,
                            GParamSpec *pspec,

diff --git a/src/cinnamon-global.h b/src/cinnamon-global.h
@@ -32,6 +32,7 @@ ClutterStage  *cinnamon_global_get_stage                 (CinnamonGlobal *global
 CinnamonScreen *cinnamon_global_get_screen                (CinnamonGlobal *global);
 MetaDisplay   *cinnamon_global_get_display               (CinnamonGlobal *global);
 GList         *cinnamon_global_get_window_actors         (CinnamonGlobal *global);
+GList         *cinnamon_global_get_background_actors     (CinnamonGlobal *global);
 GSettings     *cinnamon_global_get_settings              (CinnamonGlobal *global);
 guint32        cinnamon_global_get_current_time          (CinnamonGlobal *global);
 pid_t          cinnamon_global_get_pid                   (CinnamonGlobal *global);