Adds the ability to pin the currently developed photo to the 2nd darkroom window

[masterpiga]

This change adds two buttons to the 2nd darkroom window, making this functionality more generally useful:

1. A "pin" button to keep the 2nd window focused on the currently developed images. Changing images in the darktable main window does not affect the content of the 2nd window. This is useful to use the 2nd window as a reference, e.g., for style matching or color grading.

2. A "keep on top" button, which keeps the 2nd window on top of the main one. This is especially useful for macOS users, as the OS does not implement this functionality natively.

The two changes are bundled together because on macOS pinning the image without being able to keep it in on top greatly reduces its usefulness. Additionally, the code footprint of (2) is negligible.

The change was proposed and discussed on Pixls, and the community seemed to welcome it.

The implementation discussed on Pixls was taking a full-size snapshot of the image. Following @dterrahe's suggestions, I reimplemented it to use a separate pixelpipe for the 2nd window.

When the image is pinned, the current pipe is duplicated and the view of 2nd window updated to point to insist on the new pipe. When the image is unpinned, the 2nd pipe is destroyed and the main darkroom pipe is restored.

See demo video below:

Screen.Recording.2025-12-21.at.13.56.27.mp4

You will see a lot of examples with composite (overlay) and watermark, as the changes introduced in develop.c to be able to reuse the pipe had broken that functionality. It took me quite a bit to track down the issue and fix it. The problematic bit is documented in the code.

I tested extensively opening and closing the 2nd window, pinning and unpinning repeatedly while the main image is still being rendered, which led me to fix some issues with the 2nd window cleanup code.

I am quite confident that the logic is sound now, but I am not familiar with the pixelpipe code so a close inspection from more expert eyes is very welcome. Everything seems to work as expected, but you never know.

[wpferguson]

The change was proposed and discussed on Pixls, and the community seemed to welcome it.

In the future you might want to raise an issue in the darktable issue tracker to propose your idea. That way you get the views of a different community and make the devs whose areas you're going to touch aware. They may offer suggestions and/or help that could save you time, frustration, etc.

The reason I suggest this is what is because of what is happening with the tone equalizer PR. It started the same way (on pixls) and is currently mired in controversy.

---

Now for the PR. You mention MacOS a lot and your images are from there. Did you test on Windows or Linux?

[masterpiga]

In the future you might want to raise an issue in the darktable issue tracker to propose your idea. That way you get the views of a different community and make the devs whose areas you're going to touch aware. They may offer suggestions and/or help that could save you time, frustration, etc.

Thanks, that is good advice.

Now for the PR. You mention MacOS a lot and your images are from there. Did you test on Windows or Linux?

I tested on a virtualized Fedora and it works as intended. See video below:

Screen.Recording.2025-12-22.at.10.20.02.mp4

The video also shows how you can pin at any point in history, not just at the current edit state.

I have no way of testing on Windows unfortunately, the last time that I used windows was when XP came out.

[masterpiga]

One small addition. The layout of the two buttons in the 2nd window currently is hard coded. I would argue that it would make sense to make this more customizable, but I would prefer to do that in a follow up PR.

Also, I would like to attach actions to the two toggle buttons so that they can controlled via keyboard shortcuts. I had started doing that but then I noticed that the "quick shortcut" overlay does not work on the 2nd window, so it probably requires more work. I would also leave that for a follow up, in case.

[TurboGit]

@masterpiga : Not tested yet as this needs a conflict resolution. I see on the video that the two new icons are vertically aligned, maybe better to have then vertically aligned to avoid loosing spaces on the border? Or maybe it is already the case if the window is made shorter?

[TurboGit]

@masterpiga : Please, do not merge master into your topic branch. You need to rebase on top of current master and fix the conflicts. TIA.

[masterpiga]

Done, @TurboGit. I stacked the buttons vertically as you suggested.

I considered making the orientation switch based on the size of the window, but moving controls around is not too great from a UX point of view, so I would rather stick to either vertical or horizontal layout.

[masterpiga]

Pushed a new snapshot, I had accidentally reverted the additions to darktable.css.

[TurboGit]

Tested today. I have two requests:

1. The "stays on top" does not work on GNU/Linux
2. I'd like the two buttons to hide themself after some time and be drawn again when the mouse is close. Something similar is done on the histogram.

[masterpiga]

Thanks for trying it @TurboGit.

The buttons now show when the pointer enters the 2nd window, as you asked.

As for keep on top not working on Linux, I cannot reproduce it.

Here is it running on a virtualized fedora, where it WAI:

Screen.Recording.2026-02-22.at.15.13.58.mp4

[TurboGit]

As for keep on top not working on Linux, I cannot reproduce it.

Here is it running on a virtualized fedora, where it WAI:

Thanks for trying it @TurboGit.

The buttons now show when the pointer enters the 2nd window, as you asked.

As for keep on top not working on Linux, I cannot reproduce it.

Here is it running on a virtualized fedora, where it WAI:
Screen.Recording.2026-02-22.at.15.13.58.mp4

Maybe a Wayland issue. Is the VM on Wayland or X11?

[masterpiga]

I believe it's X11:

$ echo $XDG_SESSION_TYPE 
x11

Edit: Yes, I switched to Wayland and it does not work. Let me try to fix it.

[masterpiga]

So, @TurboGit.

IIUC, the best way to fix this would be to mark the 2nd window as transient_for the main window. This would make the 2nd window be always on top of the main window, and would work also on Wayland (tested). IMHO, this would be the right approach:

1. We can get rid of the "keep on top" button, because the 2nd window is always on top
2. Since it is a reference window, it kind of makes sense that it stays on top
3. If the user doesn't want it on top, they can just disable the 2nd window and re-enable it when they want it

Note that setting transient_for is necessary for the tooltips to show on Wayland. If we do not care about the tooltips, we can also use transient_for to toggle the on-top behavior.

WDYT?

[TurboGit]

I agree with that. Always on top and then if this is not wanted the user can indeed disable the second window. Seems to cover almost all cases to me. So we keep a single button on the second window to pin the image.

[masterpiga]

Done, @TurboGit.

This is on Wayland:

Screen.Recording.2026-02-23.at.07.36.41.mp4

Tested also on macOS and X11.

• 2nd window stays always on top via transient_for
• Focus follows the mouse to enable tooltip display with no need to click the 2nd window
• Pin button only shows when 2nd window focused/hovered

[TurboGit]

Works for me, thanks!

[masterpiga]

Yay, thanks @TurboGit, I hope it will turn out to be a useful feature.