Document background effects

docs/mkdocs.yaml

@@ -85,6 +85,7 @@ nav:
     - Xwayland: Xwayland.md
     - Gestures: Gestures.md
     - Fullscreen and Maximize: Fullscreen-and-Maximize.md
+    - Window Effects: Window-Effects.md
     - Packaging niri: Packaging-niri.md
     - Integrating niri: Integrating-niri.md
     - Accessibility: Accessibility.md

docs/wiki/Configuration:-Layer-Rules.md

@@ -35,6 +35,13 @@ layer-rule {
     geometry-corner-radius 12
     place-within-backdrop true
     baba-is-float true
+
+    background-effect {
+        xray true
+        blur true
+        noise 0.05
+        saturation 3
+    }
 }
 ```
 
@@ -208,3 +215,29 @@ layer-rule {
     baba-is-float true
 }
 ```
+
+#### `background-effect`
+
+<sup>Since: next release</sup>
+
+Override the background effect options for this surface.
+
+- `xray`: set to `true` to enable the xray effect, or `false` to disable it.
+- `blur`: set to `true` to enable blur behind this surface, or `false` to force-disable it.
+- `noise`: amount of pixel noise added to the background (helps with color banding from blur).
+- `saturation`: color saturation of the background (`0` is desaturated, `1` is normal, `2` is 200% saturation).
+
+See the [window effects page](./Window-Effects.md) for an overview of background effects.
+
+```kdl
+// Make top and overlay layers use the regular blur (if enabled),
+// while bottom and background layers keep using the efficient xray blur.
+layer-rule {
+    match layer="top"
+    match layer="overlay"
+
+    background-effect {
+        xray false
+    }
+}
+```

docs/wiki/Configuration:-Miscellaneous.md

@@ -54,6 +54,14 @@ hotkey-overlay {
 config-notification {
     disable-failed
 }
+
+blur {
+    // off
+    passes 3
+    offset 3.0
+    noise 0.02
+    saturation 1.5
+}
 ```
 
 ### `spawn-at-startup`
@@ -320,3 +328,81 @@ config-notification {
     disable-failed
 }
 ```
+
+### `blur`
+
+<sup>Since: next release</sup>
+
+Blur configuration that affects all background blur.
+
+See the [window effects page](./Window-Effects.md) for an overview of background effects.
+
+```kdl
+blur {
+    // off
+    passes 3
+    offset 3
+    noise 0.02
+    saturation 1.5
+}
+```
+
+#### `off`
+
+By default, blur is available on request by a window or layer surface (via the `ext-background-effect` protocol).
+You can also enable it manually with the `blur true` background effect [window](./Configuration:-Window-Rules.md#background-effect) or [layer](./Configuration:-Layer-Rules.md#background-effect) rule.
+
+Setting the `off` flag will disable all blur, both requested by the window, and configured in window rules.
+
+```kdl
+blur {
+    off
+}
+```
+
+#### `passes` and `offset`
+
+`passes` contols the number of downsample/upsample passes for dual kawase blur.
+More passes produce a larger, smoother blur, but cost more GPU resources.
+
+`offset` is the pixel offset multiplier for each pass.
+Offset `1` is the original dual kawase blur.
+Larger values produce a smoother blur, at no additional GPU cost.
+
+However, setting `offset` too big will produce visual artifacts.
+You will need to increase `passes` to be able to use a bigger `offset` without artifacts.
+
+When configuring blur, try increasing `offset` first (since it doesn't cause any extra GPU load) until you start getting artifacts.
+Then, if you still need smoother blur, increase `passes` by 1.
+Keep doing this until you get the desired visuals. 
+
+```kdl
+blur {
+    passes 3
+    offset 3.0
+}
+```
+
+#### `noise`
+
+Amount of noise to add on top of the blur.
+
+This is helpful to reduce color banding artifacts.
+
+```kdl
+blur {
+    noise 0.02
+}
+```
+
+#### `saturation`
+
+Color saturation applied to the blurred background.
+
+Values above `1` increase saturation; values below `1` reduce it.
+
+```kdl
+blur {
+    saturation 1.5
+}
+```

docs/wiki/Configuration:-Window-Rules.md

@@ -100,6 +100,13 @@ window-rule {
     tiled-state true
     baba-is-float true
 
+    background-effect {
+        xray true
+        blur true
+        noise 0.05
+        saturation 3
+    }
+
     min-width 100
     max-width 200
     min-height 300
@@ -909,6 +916,31 @@ https://github.com/user-attachments/assets/3f4cb1a4-40b2-4766-98b7-eec014c19509
 
 </video>
 
+#### `background-effect`
+
+<sup>Since: next release</sup>
+
+Override the background effect options for this window.
+
+- `xray`: set to `true` to enable the xray effect, or `false` to disable it.
+- `blur`: set to `true` to enable blur behind this window, or `false` to force-disable it.
+- `noise`: amount of pixel noise added to the background (helps with color banding from blur).
+- `saturation`: color saturation of the background (`0` is desaturated, `1` is normal, `2` is 200% saturation).
+
+See the [window effects page](./Window-Effects.md) for an overview of background effects.
+
+```kdl
+// Make floating windows use the regular blur (if enabled),
+// while tiled windows keep using the efficient xray blur.
+window-rule {
+    match is-floating=true
+
+    background-effect {
+        xray false
+    }
+}
+```
+
 #### Size Overrides
 
 You can amend the window's minimum and maximum size in logical pixels.

docs/wiki/Window-Effects.md

@@ -0,0 +1,53 @@
+### Overview
+
+<sup>Since: next release</sup>
+
+You can apply background effects to windows and layer-shell surfaces.
+These include blur, xray, saturation, and noise.
+They can be enabled in the `background-effect {}` section of [window](./Configuration:-Window-Rules.md#background-effect) or [layer](./Configuration:-Layer-Rules.md#background-effect) rules.
+
+The window needs to be semitransparent for you to see the background effect (otherwise it's fully covered by the opaque window).
+Focus ring and border can also cover the background effect, see [this FAQ entry](./FAQ.md#why-are-transparent-windows-tinted-why-is-the-borderfocus-ring-showing-up-through-semitransparent-windows) for how to change this.
+
+### Blur
+
+Windows and layer surfaces can request their background to be blurred via the [`ext-background-effect` protocol](https://wayland.app/protocols/ext-background-effect-v1).
+In this case, the application will usually offer some "background blur" setting that you'll need to enable in its configuration.
+
+You can also enable blur on the niri side with the `blur true` background effect window rule:
+
+```kdl
+// Enable blur behind the foot terminal.
+window-rule {
+    match app-id="^foot$"
+
+    background-effect {
+        blur true
+    }
+}
+
+// Enable blur behind the fuzzel launcher.
+layer-rule {
+    match namespace="^launcher$"
+
+    background-effect {
+        blur true
+    }
+}
+```
+
+Blur enabled via the window rule will follow the window corner radius set via [`geometry-corner-radius`](./Configuration:-Window-Rules.md#geometry-corner-radius).
+On the other hand, blur enabled through `ext-background-effect` will exactly follow the shape requested by the window.
+If the window or layer has clientside rounded corners or other complex shape, it should set a corresponding blur shape through `ext-background-effect`, then it will get correctly shaped background blur without any manual niri configuration.
+
+Global blur settings are configured in the [`blur {}` config section](./Configuration:-Miscellaneous.md#blur) and apply to all background blur.
+
+### Xray
+
+Xray makes the window background "see through" to your wallpaper, ignoring any other windows below.
+You can enable it with `xray true` background effect [window](./Configuration:-Window-Rules.md#background-effect) or [layer](./Configuration:-Layer-Rules.md#background-effect) rule.
+
+Xray is automatically enabled by default if any other background effect (like blur) is active.
+This is because it's much more efficient: with xray active, niri only needs to blur the background once, and then can reuse this blurred version with no extra work (since the wallpaper changes very rarely).
+
+If you have an animated wallpaper, xray will still have to recompute blur every frame, but that happens once and shared among all windows, rather than recomputed separately for each window.

docs/wiki/_Sidebar.md

@@ -14,6 +14,7 @@
 * [Xwayland](./Xwayland.md)
 * [Gestures](./Gestures.md)
 * [Fullscreen and Maximize](./Fullscreen-and-Maximize.md)
+* [Window Effects](./Window-Effects.md)
 * [Packaging niri](./Packaging-niri.md)
 * [Integrating niri](./Integrating-niri.md)
 * [Accessibility](./Accessibility.md)