From 76e1baf9ae796feb3d9bbc7a059f1535d92a6bac Mon Sep 17 00:00:00 2001
From: vaxerski <43317083+vaxerski@users.noreply.github.com>
Date: Thu, 28 Sep 2023 21:58:51 +0100
Subject: [PATCH] add tearing notes

---
 pages/Configuring/Tearing.md      | 46 +++++++++++++++++++++++++++++++
 pages/Configuring/Variables.md    |  1 +
 pages/Configuring/Window-Rules.md |  1 +
 3 files changed, 48 insertions(+)
 create mode 100644 pages/Configuring/Tearing.md

diff --git a/pages/Configuring/Tearing.md b/pages/Configuring/Tearing.md
new file mode 100644
index 0000000..3183243
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/pages/Configuring/Variables.md b/pages/Configuring/Variables.md
index 2114b05..9678fd0 100644
--- a/pages/Configuring/Variables.md
+++ b/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 >}}
diff --git a/pages/Configuring/Window-Rules.md b/pages/Configuring/Window-Rules.md
index 9a0e8b6..1966ff5 100644
--- a/pages/Configuring/Window-Rules.md
+++ b/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) | &check; | 
 | group \[options\] | set window group properties. See the note below. | |
+| immediate | forces the window to allow to be torn. See [the Tearing page](../Tearing). | &check; |
 
 {{< hint type=info >}}