add tearing notes

pages/Configuring/Tearing.md

@@ -0,0 +1,46 @@
+Screen tearing is used to reduce latency and/or jitter in games.
+
+## Enabling tearing
+
+To enable tearing:
+ - Set `general:allow_tearing` to `true`. This is a "master toggle"
+ - Add `env = WLR_DRM_NO_ATOMIC,1` to your Hyprland config. This disables the usage of a newer DRM API that doesn't support tearing yet.
+ - Add an `immediate` windowrule to your game of choice. This makes sure that Hyprland will tear it.
+
+{{< hint type=note >}}
+Please note that tearing will only be in effect when the game is in fullscreen and the only thing visible on the screen.
+{{< /hint >}}
+
+Example snippet:
+```env
+general {
+    allow_tearing = true
+}
+
+env = WLR_DRM_NO_ATOMIC,1
+
+windowrulev2 = immediate, class:^(cs2)$
+```
+
+{{< hint type=warning >}}
+If you experience graphical issues, you may be out of luck. Tearing support is experimental.
+
+See the likely culprits below.
+{{< /hint >}}
+
+## Common issues
+
+### Graphical artifacts (random colorful pixels, etc)
+Likely issue with your graphics driver. Please note, afaik, intel's iGPUs do not support tearing at all.
+
+Please _do not_ report issues if this is the culprit. Unfortunately, it's most likely your GPU driver's fault.
+
+Could be the below as well
+
+### Other graphical issues 
+Likely issue with `WLR_DRM_NO_ATOMIC`.
+
+NO_ATOMIC forces the use of a legacy, less tested drm API.
+
+Please _do not_ report issues if this is the culprit. Unfortunately, you will have to wait for the Linux kernel to support
+tearing page flips on the atomic API.

pages/Configuring/Variables.md

@@ -66,6 +66,7 @@ SHIFT CAPS CTRL/CONTROL ALT MOD2 MOD3 SUPER/WIN/LOGO/MOD4 MOD5
 | resize_on_border | enables resizing windows by clicking and dragging on borders and gaps | bool | false |
 | extend_border_grab_area | extends the area around the border where you can click and drag on, only used when `general:resize_on_border` is on. | int | 15 |
 | hover_icon_on_border | show a cursor icon when hovering over borders, only used when `general:resize_on_border` is on. | bool | true |
+| allow_tearing | master switch for allowing tearing to occur. See [the Tearing page](../Tearing). | bool | false |
 
 
 {{< hint type=warning >}}

pages/Configuring/Window-Rules.md

@@ -115,6 +115,7 @@ you can use `hyprctl clients`.
 | stayfocused | forces focus on the window as long as it's visible |  |
 | xray \[on\] | sets blur xray mode for the window (0 for off, 1 for on, unset for default) | ✓ | 
 | group \[options\] | set window group properties. See the note below. | |
+| immediate | forces the window to allow to be torn. See [the Tearing page](../Tearing). | ✓ |
 
 {{< hint type=info >}}