docs: win32_system_backdrop

refs: #3528 refs: #1614
wez · Apr 17, 2023 · 38da9d7 · 38da9d7
1 parent 163dfd7
commit 38da9d7
Show file tree

Hide file tree

Showing 7 changed files with 80 additions and 0 deletions.
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -24,6 +24,7 @@ As features stabilize some brief notes about them will accumulate here.
 #### New
 
 * [window:keyboard_modifiers](config/lua/window/keyboard_modifiers.md) #3444
+* [win32_system_backdrop](config/lua/config/win32_system_backdrop.md). Thanks to @kingavatar! #3528 #1614
 
 #### Fixed
 

diff --git a/docs/config/lua/config/macos_window_background_blur.md b/docs/config/lua/config/macos_window_background_blur.md
@@ -22,3 +22,6 @@ config.macos_window_background_blur = 20
 ![Screenshot](../../../screenshots/wezterm-macos-background-blur.png)
 
 The default value for `macos_window_background_blur` is `0`.
+
+See also [win32_system_backdrop](win32_system_backdrop.md) for a similar
+effect on Windows.
diff --git a/docs/config/lua/config/win32_acrylic_accent_color.md b/docs/config/lua/config/win32_acrylic_accent_color.md
@@ -0,0 +1,14 @@
+---
+tags:
+  - appearance
+---
+
+# `win32_acrylic_accent_color = COLOR`
+
+{{since('nightly')}}
+
+When combined with `win32_system_backdrop = "Acrylic"` on Windows systems
+earlier than build 22621, this option specifies the accent color used with
+the *Acrylic* composition effect.
+
+See also [win32_system_backdrop](win32_system_backdrop.md).
diff --git a/docs/config/lua/config/win32_system_backdrop.md b/docs/config/lua/config/win32_system_backdrop.md
@@ -0,0 +1,62 @@
+---
+tags:
+  - appearance
+---
+
+# `win32_system_backdrop = SETTING`
+
+{{since('nightly')}}
+
+When combined with `window_background_opacity`, chooses from available
+window background effects provided by Windows.
+
+The possible values for `win32_system_backdrop` are:
+
+* `"Auto"` - the system chooses. In practice, this is the same as `"Disable"`. This is the default value.
+* `"Disable"` - disable backdrop effects.
+* `"Acrylic"` - enable the *Acrylic* blur-behind-window effect.  Available on Windows 10 and 11.
+* `"Mica"` - enable the *Mica* effect, available on Windows 11 build 22621 and later.
+* `"Tabbed"` - enable the *Tabbed* effect, available on Windows 11 build 22621 and later.
+
+On Windows systems earlier than build 22621, the *Acrylic* affect can be
+adjusted using [win32_acrylic_accent_color](win32_acrylic_accent_color.md).
+More recent versions of Windows do not permit configuring the accent color
+for *Acrylic*, so that option has no effect there.
+
+The *Acrylic* setting uses more resources than the others.
+
+You need to reduce the `window_background_opacity` to a value lower than `1.0`
+for the backdrop effect to work.  For best results with both `"Mica"` and
+`"Tabbed"`, setting `window_background_opacity = 0` is recommended.
+
+See also [macos_window_background_blur](macos_window_background_blur.md) for
+a similar effect on macOS.
+
+## Acrylic
+
+```lua
+config.window_background_opacity = 0
+config.win32_system_backdrop = 'Acrylic'
+```
+
+![Acrylic Effect](../../../screenshots/wezterm-acrylic.png)
+
+## Mica
+
+```lua
+config.window_background_opacity = 0
+config.win32_system_backdrop = 'Mica'
+```
+
+![Mica Effect](../../../screenshots/wezterm-mica.png)
+
+## Tabbed
+
+```lua
+config.window_background_opacity = 0
+config.win32_system_backdrop = 'Tabbed'
+```
+
+![Tabbed Effect](../../../screenshots/wezterm-tabbed.png)
+
+
diff --git a/docs/screenshots/wezterm-acrylic.png b/docs/screenshots/wezterm-acrylic.png
diff --git a/docs/screenshots/wezterm-mica.png b/docs/screenshots/wezterm-mica.png
diff --git a/docs/screenshots/wezterm-tabbed.png b/docs/screenshots/wezterm-tabbed.png