`experimental.useBackgroundImageForWindow` isn't working right

[vunhatchuong]

Description of the new feature/enhancement

I want to use Windows Terminal like tmux, But the background image doesn't stay as one with multiple panes.

Proposed technical implementation details (optional)

Make multiple panes use the same background

[j4james]

There's an experimental setting called experimental.useBackgroundImageForWindow which I think is probably what you're asking for. See PR #12893.

[vunhatchuong]

Yep, that's what I'm looking, but it behaves really weird currently. This is with both background and background image 100% opacity.

[j4james]

Yeah, that's weird. I got the same thing on the preview version of the terminal (1.16.2641.0), but not on my dev build. I tried synchronizing the settings between the two versions to see if there was a particular setting that might be to blame, but that didn't seem to make any difference. I then tried restarting the terminal, and that fixed it.

So you may find that restarting helps, but there may also be some setting you need to change as well. Unfortunately I didn't think to backup my settings before messing with them, so I have no idea what they were when when it was broken.

Bottom line is I suspect there's a bug somewhere in this feature, but I can't reproduce it anymore. IF you can still reproduce it after a restart, it might help if you uploaded a copy of your settings here. Also what version of the terminal you're using.

[vunhatchuong]

My version is same as yours. The bug still exist even after restart.

I tried every settings I can see in the config and nothing fix it, don't know about experimental features.

[lhecker]

Should we just repurpose this issue as a bug report for experimental.useBackgroundImageForWindow not working correctly?

[carlos-zamora]

Should we just repurpose this issue as a bug report for experimental.useBackgroundImageForWindow not working correctly?

Yeah, we should.

@vunhatchuong123 could you provide us with a copy of your settings.json so that we can debug this issue?

[237dmitry]

[DHowett]

I'm sorry, I think I'm going to need an executive summary of exactly how it's not working properly (or how it is "really weird".)

Is it transparent when it should not be?

[vunhatchuong]

Is it transparent when it should not be?

Yes, It's completely transparent despite me putting background image opacity to 100% or background opacity to 100%.

settings.json

{
    "actions": 
    [
    ],
    "centerOnLaunch": true,
    "experimental.useBackgroundImageForWindow": true,
    "copyFormatting": "none",
    "copyOnSelect": false,
    "defaultProfile": "{574e775e-4f2a-5b96-ac1e-a2962a402336}",
    "disableAnimations": true,
    "initialCols": 160,
    "initialRows": 45,
    "launchMode": "focus",
    "profiles": 
    {
        "defaults": 
        {
            "backgroundImage": "C:\\Users\\Ronny\\AppData\\Local\\Packages\\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\\LocalState\\ctpayamir.png",
            "backgroundImageOpacity": 0.25,
            "backgroundImageStretchMode": "uniformToFill",
            "bellStyle": "none",
            "colorScheme": "Catppuccin Mocha",
            "cursorShape": "filledBox",
            "elevate": false,
            "font": 
            {
                "face": "JetBrainsMono NFM"
            },
            "opacity": 95,
            "padding": "8",
            "scrollbarState": "hidden",
            "useAcrylic": false
        },
        "list": 
        [
            {
                "commandline": "pwsh.exe -nologo",
                "guid": "{574e775e-4f2a-5b96-ac1e-a2962a402336}",
                "hidden": false,
                "name": "PowerShell",
                "source": "Windows.Terminal.PowershellCore"
            },
            {
                "guid": "{f9ceaf27-504c-58d7-927c-d1d6a7ac7d3c}",
                "hidden": false,
                "name": "Ubuntu 22.04.1 LTS",
                "source": "CanonicalGroupLimited.Ubuntu22.04LTS_79rhkp1fndgsc"
            },
            {
                "guid": "{17bf3de4-5353-5709-bcf9-835bd952a95e}",
                "hidden": true,
                "name": "Ubuntu-22.04",
                "source": "Windows.Terminal.Wsl"
            },
            {
                "commandline": "%SystemRoot%\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
                "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
                "hidden": false,
                "name": "Windows PowerShell"
            },
            {
                "commandline": "%SystemRoot%\\System32\\cmd.exe",
                "guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
                "hidden": false,
                "name": "Command Prompt"
            },
            {
                "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}",
                "hidden": false,
                "name": "Azure Cloud Shell",
                "source": "Windows.Terminal.Azure"
            }
        ]
    },
    "schemes": 
    [
        {
            "background": "#1E1E2E",
            "black": "#45475A",
            "blue": "#89B4FA",
            "brightBlack": "#585B70",
            "brightBlue": "#89B4FA",
            "brightCyan": "#94E2D5",
            "brightGreen": "#A6E3A1",
            "brightPurple": "#F5C2E7",
            "brightRed": "#F38BA8",
            "brightWhite": "#A6ADC8",
            "brightYellow": "#F9E2AF",
            "cursorColor": "#F5E0DC",
            "cyan": "#94E2D5",
            "foreground": "#CDD6F4",
            "green": "#A6E3A1",
            "name": "Catppuccin Mocha",
            "purple": "#F5C2E7",
            "red": "#F38BA8",
            "selectionBackground": "#F5E0DC",
            "white": "#BAC2DE",
            "yellow": "#F9E2AF"
        },
    ],
    "theme": "Catppuccin Mocha",
    "themes": 
    [
        {
            "name": "Catppuccin Mocha",
            "tab": 
            {
                "background": "#313244FF",
                "showCloseButton": "always",
                "unfocusedBackground": null
            },
            "tabRow": 
            {
                "background": "#1E1E2EFF",
                "unfocusedBackground": "#181825FF"
            },
            "window": 
            {
                "applicationTheme": "dark"
            }
        }
    ]
}

[j4james]

Is it transparent when it should not be?

Yep. And I'm on Windows 10, so I didn't think transparent windows were even possible. I've actually just reproduced it again now. The trick seems to be having the backgroundImageOpacity as something less than 1, but you also then need to restart the terminal for it to take affect. And note that the opacity setting is still 100.

[vunhatchuong]

I think how @j4james described above is more correct, it's exactly my issue.

[j4james]

Without knowing anything about this code, I've got to say this line looks awfully suspicious... https://github.com/microsoft/terminal/blob/43dbbd590fa4b46c37e9970415f8150d3c399598/src/cascadia/TerminalControl/TermControl.cpp#L531

Unfortunately my dev build won't even start up without crashing at the moment, so I'm not in a position to experiment.

Edit: Ignore this. It looks like this code is just stopping the background color of each pane from blocking out the image.

[237dmitry]

In my environment all works fine but Acrylic. Need WT restarting. 1.16.2642.0

      "opacity": 0,                             //  Work with any value
      "backgroundImage": "%UserProfile%\\Path\\To\\picture.png",
      "backgroundImageAlignment": "topLeft",
      "backgroundImageOpacity": 0.9,
      "backgroundImageStretchMode": "fill",
      "useAcrylic": true,                      // Not working at all. Not sure if this should work.

[elsaco]

I don't get what the issue is! With the useBackgroundImageForWindow set the background image is expanded beneath other panes:

and this is with the settings false:

If only useBackgroundImageForWindows is set and no backgroundImage is specified then the window background is transparent. Test was done on Win10 with terminal 1.16.2641.0.

[DHowett]

@elsaco @237dmitry thanks again for adding your input (as on other issues!) It may be working for you, but it clearly isn't working properly for @j4james or the original filer of this bug. That's sort-of why we consider it a bug!

I appreciate you confirming that it isn't broken for everybody. That can provide useful information to the team.

[psmolkin]

I can confirm, it's broken for me too. win10: 19044 WT: 1.16.2641.0 When "experimental.useBackgroundImageForWindow": true the background (not background image) just disapears. And the "opacity": option doesn't make sense. Only the "backgroundImageOpacity": option does something. And that only after the restart of WT

[zadjii-msft]

Ho boy I think I see this too, but maybe differently? If I set one pane to have a background image, and set experimental.useBackgroundImageForWindow: true, then that works just fine. It's just every other tab or pane that doesn't have a backgound image - they're all transparent now 😬

notes:

there's a couple things going on

• [ ] with useBGForWindow set, focusing a pane w/o an image makes every pane with an image transparent. Yikes.
• [ ] set useBGForWindow:true, focus a pane with an image, then set it to useBGForWindow:false, and observe a pane with <100 opacity. You'll be able to see the BG image left behind!
• [ ] whatever OP was seeing

[zadjii-msft]

Alright I'm seeing a bunch of different things, so lemme try and teas these out:

---

@vunhatchuong123

This is with both background and background image 100% opacity.

That doesn't look true to me from the settings.json you posted.

    "profiles": 
    {
        "defaults": 
        {
            "backgroundImage": "C:\\Users\\Ronny\\AppData\\Local\\Packages\\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\\LocalState\\ctpayamir.png",
            "backgroundImageOpacity": 0.25,
            "backgroundImageStretchMode": "uniformToFill",
			// ...
            "opacity": 95,

In that blob, the "backgroundImageOpacity": 0.25, is the value being used for the whole window's BG image, hence the mostly transparent window you're seeing.

---

Possibly related: It looks like the opacity of the whole-window BG image wouldn't hot reload if the path didn't. That I have a fix for, 14e270d57

---

set useBGForWindow:true, focus a pane with an image, then set it to useBGForWindow:false, and observe a pane with <100 opacity. You'll be able to see the BG image left behind!

This I have a fix for, fdb6752da

---

My above gif: https://github.com/microsoft/terminal/issues/14260#issuecomment-1322740578

with useBGForWindow set, focusing a pane w/o an image makes every pane with an image transparent. Yikes

This firmly falls into "we didn't spec this, this is undefined behavior" territory. Glad we left experimental here!

What do? With this setting enabled, and a profile w/o an image focused,

• should we still display the BG image in the pane with the image?
  • not sure this is trivially possible - it would require TermControl's communicating with each other in a very layer breaking way
• Do we just fill in the whole BG texture of the focused control? Acrylic and all?
• Do we make this setting a per-profile one, so focusing a pane w/o this setting enabled would just disable it?
• Do we just toss this setting and replace it with a theme one?
  • would not work for two images in two different SxS panes

[j4james]

In that blob, the "backgroundImageOpacity": 0.25, is the value being used for the whole window's BG image, hence the mostly transparent window you're seeing.

If this is the way it's intended to work, then so be it, but I've got to say it's really confusing.

With useBackgroundImageForWindow false, the backgroundImageOpacity setting has a kind of saturating effect, determining to what extent the image is mixed with the background color, and the opacity setting determines the acrylic transparency level.

With useBackgroundImageForWindow true, the backgroundImageOpacity appears to take on a whole new meaning, controlling the pure transparency of the window. There is no acrylic effect anymore, and the opacity setting makes no difference whatsoever.

In case this is something specific to Windows 10, I've included a bunch of screenshots below demonstrating what I'm seeing. From left to right, the backgroundImageOpacity varies between 0.0, 0.5, and 1.0, and from top to bottom, the opacity varies between 0, 50, and 100.

The first set of images is with useBackgroundImageForWindow false, and the second set is with it true. Note how the opacity has no effect in the second set. And the text you're seeing is from a copy of notepad behind the terminal showing my settings - that's just blurred out by the acrylic in the first set.

useBackgroundImageForWindow false

useBackgroundImageForWindow true

[zadjii-msft]

I've got to say it's really confusing

YEA, it is really confusing. I've got a TODO on my whiteboard to ping the original thread about this, cause the whole feature is terribly confusing. It's got maybe too many edge cases. IMO, I want to remove that and replace it with a Theme property window.background{ .opacity, .alignment, ...}. It would be a very different experience, but might actually make more sense.

I just gotta take the time to write something up 😅

[Elvynia]

I thought of opening an issue because of a window opacity problem when using experimental.useBackgroundImageForWindow. But after reading comments on this issue I don't think it would be useful so I'll just give feedback here.

I installed experimental version of windows terminal 1.16.10261.0 to use experimental.useBackgroundImageForWindow but was forced to remove it due to opacity window always 0, making text illegible despite trying all possible configurations.

Here is the profile configuration I am using:

"defaults": 
        {
            "adjustIndistinguishableColors": "indexed",
            "backgroundImage": "desktopWallpaper",
            "backgroundImageOpacity": 0.35,
            "backgroundImageStretchMode": "uniformToFill",
            "colorScheme": "Campbell",
            "font": 
            {
                "size": 13.0,
                "weight": "medium"
            },
            "intenseTextStyle": "bright",
            "opacity": 100,
            "padding": "0",
            "useAcrylic": true
        }

It works well without the experimental feature. I see my windows wallpaper with 35% opacity but the window using opacity 100% is fully solid.

With the experimental feature on and the same configuration, backgroundImageOpacity is working right but window opacity is always 0. If I use backgroundImageOpacity below 100%, I will automatically see behind the window (other window or windows desktop using the same image).

I even tried to disable windows transparency in personalization parameters but no changes. Also disabling acrylic option in windows terminal parameters did not change anything. If you have a workaround I'll gladly test it !

[lightspeed3m]

I used https://pinetools.com/darken-image and set "backgroundImageOpacity": 1 as a workaround.

Edit: In addition to the "darken" effect, having backgroundImageOpacity set to ~0.95 to 0.98 produces an acrylic-like effect without a blur.