Skip to content

Keep preview decoding shared through late display-scale changes - #139

Merged
dhh merged 3 commits into
omacom:mainfrom
claytonfaria:perf/defer-preview-image-load
Nov 18, 2026
Merged

dhh merged 3 commits into
omacom:mainfrom
claytonfaria:perf/defer-preview-image-load

Conversation

@claytonfaria

@claytonfaria claytonfaria commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Large still images can lose their only in-flight pixmap reference when the preview window learns its final display scale. Qt finishes the abandoned decode, then reads the same file again for the replacement request.

The initial Qt.callLater deferral was insufficient: the compositor can settle the window's DPR after the first frame, as demonstrated in the review. This revision removes that deferral.

Keep a second reference while the visible image is Loading, using an invisible Image child with the same window, source and autoTransform options. Sequential scale reloads can join the shared in-flight request instead of cancelling its last reference. The keeper clears its source at Ready/Error; full resolution, geometry and navigation remain unchanged.

The keeper is a visual child rather than a windowless Image: on mixed-scale displays, a windowless image can resolve a different @Nx sibling or SVG rasterization. Sharing the window avoids that mismatch without sibling-file probes or private Qt APIs.

Validation:

  • A new gated-provider regression forces the consumer to reload during an in-flight request and counts actual provider calls: two without the keeper, one with it. It also checks that the keeper shares the window, is hidden, and releases its source after Ready.
  • Native Wayland tracing of the 5460 × 8192 PNG gives one QImageReader decode in each of six runs, two per effective scale 1, 1.6 and 2 (base output 1.6×, QT_SCALE_FACTOR 0.625/1/1.25).
  • Geometry, keyboard zoom/reset, navigation and destruction coverage is retained. The complete suite passes: 204 tests, 0 failures.
  • The combined Show a cached picture while the original preview loads #140 branch passes 219 tests, including scaled offscreen UI checks.

The offscreen reload test checks shared-request lifetime, not the compositor's scale-negotiation timeline; native tracing provides the startup check. No latency claims from the superseded deferral prototype are relied upon here.

Simplify and independent code-review passes completed before this update. No new dependencies or global settings changes.

@greptile-apps

greptile-apps Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge.

Summary

The preview keeps a hidden image attached to the same window while a still image loads, so scale changes can reuse work already underway.

  • Still-image previews keep a decode alive across display-scale reloads.

No actionable issues found. Tests were not run during this review.

Reviews (3) · Last reviewed commit: "Keep only the test that proves a reload ..." · Reviewed by Greptile

@omarchybot omarchybot added the bug Something isn't working label Nov 16, 2026
@omarchybot

Copy link
Copy Markdown
Contributor

Thanks for tracing this, Clayton. The double decode is real, but on a stock Omarchy install this branch still decodes the picture twice, so it can't go in as the fix yet.

What was checked. On a disposable Omarchy worker (Hyprland 0.57.2, Qt 6.12.0, qt6-wayland 6.12.0), folio preview on a 5460×8192 8-bit PNG, counting reads of the file with strace and following the pixmap cache with QT_LOGGING_RULES=qt.quick.image.debug=true:

Output scale main (41e9f41) this branch (3a3e5e8)
1.0 one decode one decode
1.6 two full decodes (3 of 3 runs) two full decodes (6 of 6 runs)
2.0 two full decodes two full decodes

Each decode reads the whole ~67 MB file on the pixmap reader thread and takes ~0.85 s, so the picture is ready ~1.6 s after the window opens instead of ~0.9 s. The full suite (bin/test) is green at 3a3e5e8 on the same worker.

Why the deferral doesn't hold here. A copy of this branch logging the window's own devicePixelRatio shows the order at 1.6: the window starts at 2, Qt.callLater fires and the load starts at 0.333 s, the first frame is drawn at 0.497 s, and only then does the window's ratio go 2 → 1 → 1.6 (0.500–0.510 s). The Image reloads on that change, which drops the only reference to the decode still in flight, and the reader decodes the file again once the first one finishes. The item already belongs to the window when the load starts; what isn't settled yet is the window's scale, and that settles after the first frame, which one event-loop pass can't wait for. It may win on a machine where the compositor answers sooner, but on this one it loses every time.

What else was checked, and holds. The deferred call can't set a stale source: it only flips readyToLoad, and source stays bound to previewer.url, so a file chosen before it fires is the one that loads. Destroying the view before it fires is safe, as the test checks. At 1.0 it delays an asynchronous load by one pass, which costs nothing visible. Setting sourceSize before source would not help either: it makes the scale part of the decode and the Image still reloads when the scale changes, and it would decode below full size.

The test checks that source is empty right after the component is created, so it proves the deferral is there rather than that the file is decoded once, and it passes on the worker while the double decode still happens. The offscreen suite runs at a fixed scale, so it can't see this bug at all.

One approach that held on the worker. Since the reload only re-requests the same image, keeping a second reference to the decode lets the reload join it instead of starting again. On main, inside Image { id: still }:

// Outside the window, so it never reloads when the window learns its scale:
// the still image reloading then joins this decode instead of starting another.
property Image keeper: Image { asynchronous: true; autoTransform: true; source: still.source }

That gave one decode at 1.0, 1.6 and 2.0, the picture ready ~0.9 s after opening, the same memory as main (both share one cache entry; VmRSS ~603 MB either way on this file), and the suite green. It depends on the two Images having the same pixmap cache key: without autoTransform: true the keys differ and it decodes twice again, and a big@2x.png beside the file would make the windowed Image load the other file. No offscreen test can guard it either. The maintainer asked for bug fixes in their simplest form, and this is one line against the deferral's five, but it is a different mechanism, so it is yours to take or not rather than something pushed to your branch. Nothing was pushed.

Second opinion. Codex Medium and muse-wonder (via pi, thinking high) reviewed the diff and these measurements. Both agreed the deferral loses the race on this worker and that the test checks the mechanism rather than the outcome; that agreement is not guaranteed independent. muse-wonder added the @2x case and the cache-key fragility of the keeper above, and both pointed out that the reload's cause was inferred until the window's ratio was logged directly, which is the timeline given here.

Waiting on: you, for a change that keeps the second decode from happening on a stock install. #140 is stacked on this branch, so whatever replaces this commit, #140 will need rebasing onto it.

@claytonfaria claytonfaria changed the title Avoid decoding the first preview image twice Keep preview decoding shared through late display-scale changes Nov 16, 2026
claytonfaria and others added 3 commits November 18, 2026 15:28
The fix is nine lines in the preview window; the tests around it had
grown to two hundred, with a stand-in previewer class and provider at
file scope and a second test of the preview's geometry, zoom and
navigation that doesn't touch the fix.

Keep the one test that counts the provider's reads across a reload
while the first decode is held: two without the keeper, one with it.
Its provider and stand-in previewer now live inside it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dhh
dhh force-pushed the perf/defer-preview-image-load branch from e64d800 to b72e54c Compare November 18, 2026 14:32
@dhh

dhh commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Thanks, Clayton. The keeper is a nice small fix, and it's the right one. I rebased it onto main and trimmed the tests to the one that proves it, so the change stays proportional to its nine lines: previewSharesAnInFlightDecodeAcrossReloads counts the provider's reads across a reload while the first decode is held, and it reads twice without the keeper and once with it. Its gated provider and stand-in previewer now live inside the test instead of at file scope. previewImageKeepsItsGeometryAndNavigation is gone: it covers the preview's geometry, zoom and navigation in general rather than this fix. That's in b72e54c on top of your two commits. The whole suite passes locally (233 tests).

@dhh
dhh merged commit e3743d8 into omacom:main Nov 18, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants