Decode theme backgrounds earlier, and at screen size (#13408)

* Decode the next theme background while the theme stages

The wipe waited 125-290ms after the transition arrived, decoding the new
wallpaper. Most stock wallpapers are WebP, which Qt decodes at full size
and scales afterwards, so a screen-sized sourceSize does not shorten it.

Start the decode earlier instead. omarchy-theme-set chooses the next
background and snapshots it before rendering templates, then sends a new
background prepare call in the background. The shell loads it into the
hidden incoming frame, so the transition finds it decoded. A prepare that
arrives after its transition is ignored, and one no transition claims is
dropped after five seconds.

The wipe now starts ~255ms after omarchy-theme-set begins instead of
~345-490ms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Decode the wallpaper at screen size instead of shipped size

Wallpapers decoded at the resolution they were shipped at: a 5120x2880
stock wallpaper took 5120x2880 of RGBA on a 1920x1200 panel, and a
transition held up to three such frames. Bind sourceSize on the
displayed wallpaper and both transition frames to the screen's physical
size. PreserveAspectCrop treats it as the area to cover, so the image
still fills the screen.

Qt scales a decode up as well as down to cover sourceSize, so the native
size is read from the file header first with magick identify, and a
wallpaper smaller than the screen decodes at its own size. The images
wait for both sizes, so nothing decodes at native size first.

Ported from #8324 onto BackgroundMedia and the prepared incoming frame.
Measured with a 5120x2880 wallpaper, the shell's GPU memory at rest
drops from 264 MiB to ~148 MiB. The size probe delays the reveal by
~30ms, which the earlier prepare still more than covers.

Co-authored-by: Ryan Yogan <ryanyogan@gmail.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Ryan Yogan <ryanyogan@gmail.com>

shell/plugins/background/Background.qml

@@ -19,6 +19,22 @@ Item {
   property string displayedBackground: ""
   property string incomingBackground: ""
   property string oldBackground: ""
+  // A theme switch names its next background before it has staged the rest of
+  // the theme, so the incoming frame can decode while that work runs. A large
+  // WebP takes ~130ms to decode at any sourceSize, which the reveal would
+  // otherwise wait out after the transition arrives.
+  property string preparedBackground: ""
+  // The prepare and transition calls travel as separate IPC clients, so a
+  // prepare can land after its transition. The path it names then must not be
+  // decoded again.
+  property string lastTransitionPath: ""
+  // Native pixel size per wallpaper path, read from the file header before
+  // the image loads. Decoding at screen size only saves memory for wallpapers
+  // at least as large as the screen: with PreserveAspectCrop Qt scales the
+  // decode up to cover sourceSize, so a smaller wallpaper would cost the
+  // screen's worth of pixels instead of its own.
+  property var nativeSizes: ({})
+  property var sizeQueue: []
   property bool finishingTransition: false
   property int backgroundVersion: 0
   property int revealStartedVersion: -1
@@ -48,6 +64,13 @@ Item {
     finalPath = String(finalPath || path).trim()
     fromPath = String(fromPath || "").trim()
     if (!path || (!force && finalPath === currentBackground)) return
+    if (path !== preparedBackground) preparedBackground = ""
+    preparedBackgroundTimer.stop()
+    lastTransitionPath = path
+    // The incoming frame gates the reveal, so its size is read first.
+    requestNativeSize(path)
+    requestNativeSize(fromPath || displayedBackground)
+    requestNativeSize(finalPath)
     currentBackground = finalPath
     backgroundVersion += 1
     revealStartedVersion = -1
@@ -60,6 +83,7 @@ Item {
     if (instant || !displayedBackground || isVideo(path) || isVideo(displayedBackground)) {
       oldBackground = ""
       incomingBackground = ""
+      preparedBackground = ""
       displayedBackground = finalPath
       revealProgress = 1
       return
@@ -107,6 +131,39 @@ Item {
     revealAnimation.restart()
   }
 
+  function prepareBackground(path) {
+    path = String(path || "").trim()
+    // Only a still that is not already on screen is worth decoding ahead.
+    if (!path || isVideo(path) || path === lastTransitionPath || path === displayedBackground) return
+    requestNativeSize(path)
+    preparedBackground = path
+    preparedBackgroundTimer.restart()
+  }
+
+  function requestNativeSize(path) {
+    if (!path || isVideo(path) || nativeSizes[path] !== undefined || sizeQueue.indexOf(path) !== -1) return
+    sizeQueue = sizeQueue.concat([path])
+    probeNextSize()
+  }
+
+  function probeNextSize() {
+    if (sizeProbe.running || sizeQueue.length === 0) return
+    sizeProbe.path = sizeQueue[0]
+    sizeProbe.command = ["magick", "identify", "-ping", "-format", "%w %h", sizeProbe.path]
+    sizeProbe.running = true
+  }
+
+  // Each theme switch names fresh snapshot paths, so keep only the sizes of
+  // the wallpapers still in play.
+  function pruneNativeSizes() {
+    var kept = {}
+    var paths = [displayedBackground, incomingBackground, oldBackground, preparedBackground]
+    for (var i = 0; i < paths.length; i++) {
+      if (paths[i] && nativeSizes[paths[i]] !== undefined) kept[paths[i]] = nativeSizes[paths[i]]
+    }
+    nativeSizes = kept
+  }
+
   function openSelector() {
     if (!bgSwitchProc.running) bgSwitchProc.running = true
   }
@@ -126,6 +183,23 @@ Item {
     onExited: root.refreshBackground()
   }
 
+  Process {
+    id: sizeProbe
+    property string path: ""
+    stdout: StdioCollector { id: sizeProbeOut }
+    onExited: function(exitCode) {
+      var parts = String(sizeProbeOut.text || "").trim().split(/\s+/)
+      var width = exitCode === 0 ? parseInt(parts[0], 10) : 0
+      var height = exitCode === 0 ? parseInt(parts[1], 10) : 0
+      var known = Object.assign({}, root.nativeSizes)
+      // An unreadable header records 0x0, which decodes at screen size.
+      known[path] = { width: width > 0 ? width : 0, height: height > 0 ? height : 0 }
+      root.nativeSizes = known
+      root.sizeQueue = root.sizeQueue.filter(function(queued) { return queued !== sizeProbe.path })
+      root.probeNextSize()
+    }
+  }
+
   Process {
     id: readlinkProc
     command: ["readlink", "-f", root.currentBackgroundLink]
@@ -156,6 +230,19 @@ Item {
     function themeTransition(fromPath: string, path: string, finalPath: string, colorsB64: string, shellB64: string): void {
       root.transitionBackgroundWithTheme(fromPath, path, finalPath, colorsB64, shellB64)
     }
+
+    function prepare(path: string): void {
+      root.prepareBackground(path)
+    }
+  }
+
+  // A prepared frame that no transition claims, say from a theme switch that
+  // failed after naming it, must not hold its decoded texture indefinitely.
+  Timer {
+    id: preparedBackgroundTimer
+    interval: 5000
+    repeat: false
+    onTriggered: root.preparedBackground = ""
   }
 
   Timer {
@@ -208,6 +295,27 @@ Item {
 
       property bool maskReady: false
 
+      // Decode the wallpaper at the size this screen can show, not the size
+      // it was shipped at. With PreserveAspectCrop Qt takes sourceSize as the
+      // area to cover, so this is the smallest decode that still fills the
+      // screen. Stock wallpapers go up to 10456x3455 (144 MB as RGBA); a
+      // 1080p laptop paid all of that for the 8 MB it can display, and paid
+      // it up to three times over during a transition. The images wait for
+      // the window's size and the wallpaper's native size so nothing is ever
+      // decoded at native size first, and a wallpaper smaller than the screen
+      // is decoded at its own size rather than scaled up to cover the screen.
+      readonly property bool sized: width > 0 && height > 0
+      readonly property int decodeWidth: sized ? Math.ceil(width * screen.devicePixelRatio) : 0
+      readonly property int decodeHeight: sized ? Math.ceil(height * screen.devicePixelRatio) : 0
+
+      function decodeSize(path) {
+        if (!sized || !path) return Qt.size(0, 0)
+        var native = root.nativeSizes[path]
+        if (native === undefined) return Qt.size(0, 0)
+        if (native.width > 0 && (native.width < decodeWidth || native.height < decodeHeight)) return Qt.size(native.width, native.height)
+        return Qt.size(decodeWidth, decodeHeight)
+      }
+
       function maybeStartReveal() {
         if (!root.incomingBackground || root.revealProgress !== 0 || maskReady) return
         if (incomingFrame.status !== Image.Ready) return
@@ -229,11 +337,15 @@ Item {
         id: base
         anchors.fill: parent
         path: root.displayedBackground
+        constrainDecode: true
+        decodeSize: panel.decodeSize(root.displayedBackground)
         onReadyChanged: {
           if (ready && root.finishingTransition) {
             root.incomingBackground = ""
             root.oldBackground = ""
+            root.preparedBackground = ""
             root.finishingTransition = false
+            root.pruneNativeSizes()
           }
         }
       }
@@ -241,7 +353,10 @@ Item {
       Image {
         id: oldFrame
         anchors.fill: parent
-        source: root.imageUrl(root.oldBackground)
+        readonly property size decode: panel.decodeSize(root.oldBackground)
+        source: decode.width > 0 ? root.imageUrl(root.oldBackground) : ""
+        sourceSize.width: decode.width
+        sourceSize.height: decode.height
         fillMode: Image.PreserveAspectCrop
         asynchronous: true
         cache: false
@@ -267,7 +382,13 @@ Item {
         Image {
           id: incomingFrame
           anchors.fill: parent
-          source: root.imageUrl(root.incomingBackground)
+          // The same URL and size as a prepared frame keeps its decoded
+          // image, so a transition to it can reveal at once.
+          readonly property string framePath: root.incomingBackground || root.preparedBackground
+          readonly property size decode: panel.decodeSize(framePath)
+          source: decode.width > 0 ? root.imageUrl(framePath) : ""
+          sourceSize.width: decode.width
+          sourceSize.height: decode.height
           fillMode: Image.PreserveAspectCrop
           asynchronous: true
           cache: false