From 49e304b1b428aa1c3bf8d27354b150f57ddff3ea Mon Sep 17 00:00:00 2001 From: xtheeq Date: Thu, 9 Jul 2026 19:42:51 +0530 Subject: [PATCH] docs: fix example code format --- .../patches/v0.15.0/configuration/monitors.md | 288 ++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 docs/patches/v0.15.0/configuration/monitors.md diff --git a/docs/patches/v0.15.0/configuration/monitors.md b/docs/patches/v0.15.0/configuration/monitors.md new file mode 100644 index 00000000..5d3dca32 --- /dev/null +++ b/docs/patches/v0.15.0/configuration/monitors.md @@ -0,0 +1,288 @@ +--- +title: Monitors +description: Manage display outputs, resolution, scaling, and tearing. +--- + +## Monitor Rules + +You can configure each display output individually using the `monitorrule` keyword. + +**Syntax:** + +```ini +monitorrule=name:Values,Parameter:Values,Parameter:Values +``` + +> **Info:** If any of the matching fields (`name`, `make`, `model`, `serial`) are set, **all** of the set ones must match to be considered a match. Use `wlr-randr` to get your monitor's name, make, model, and serial. + +### Parameters + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `name` | string | Any | Match by monitor name (supports regex) | +| `make` | string | Any | Match by monitor manufacturer | +| `model` | string | Any | Match by monitor model | +| `serial` | string | Any | Match by monitor serial number | +| `width` | integer | 0-9999 | Monitor width | +| `height` | integer | 0-9999 | Monitor height | +| `refresh` | float | 0.001-9999.0 | Monitor refresh rate | +| `x` | integer | 0-99999 | X position | +| `y` | integer | 0-99999 | Y position | +| `scale` | float | 0.01-100.0 | Monitor scale | +| `vrr` | integer | 0, 1 | Enable variable refresh rate | +| `hdr` | integer | 0, 1 | Enable hdr support | +| `rr` | integer | 0-7 | Monitor transform | +| `custom` | integer | 0, 1 | Enable custom mode (not supported on all displays — may cause black screen) | +| `disable` | integer | 0, 1 | Disable the monitor | + +### Transform Values + +| Value | Rotation | +| :--- | :--- | +| `0` | No transform | +| `1` | 90° counter-clockwise | +| `2` | 180° counter-clockwise | +| `3` | 270° counter-clockwise | +| `4` | 180° vertical flip | +| `5` | Flip + 90° counter-clockwise | +| `6` | Flip + 180° counter-clockwise | +| `7` | Flip + 270° counter-clockwise | + +> **Critical:** If you use XWayland applications, **never use negative coordinates** for your monitor positions. This is a known XWayland bug that causes click events to malfunction. Always arrange your monitors starting from `0,0` and extend into positive coordinates. + +> **Note:** that "name" is a regular expression. If you want an exact match, you need to add `^` and `$` to the beginning and end of the expression, for example, `^eDP-1$` matches exactly the string `eDP-1`. + +### Examples + +```ini +# Laptop display: 1080p, 60Hz, positioned at origin +monitorrule=name:^eDP-1$,width:1920,height:1080,refresh:60,x:0,y:10 + +# Match by make and model instead of name +monitorrule=make:Chimei Innolux Corporation,model:0x15F5,width:1920,height:1080,refresh:60,x:0,y:0 + +# Virtual monitor with pattern matching +monitorrule=name:HEADLESS-.*,width:1920,height:1080,refresh:60,x:1926,y:0,scale:1,rr:0,vrr:0 +``` + +--- + +## Monitor Spec Format + +Several commands (`focusmon`, `tagmon`, `disable_monitor`, `enable_monitor`, `toggle_monitor`, `viewcrossmon`, `tagcrossmon`) accept a **monitor_spec** string to identify a monitor. + +**Format:** + +```text +name:xxx&&make:xxx&&model:xxx&&serial:xxx +``` + +- Any field can be omitted and there is no order requirement. +- If all fields are omitted, the string is treated as the monitor name directly (e.g., `eDP-1`). +- Use `wlr-randr` to find your monitor's name, make, model, and serial. + +**Examples:** + +```bash +# By name (shorthand) +mmsg dispatch toggle_monitor,eDP-1 + +# By make and model +mmsg dispatch toggle_monitor,make:Chimei Innolux Corporation&&model:0x15F5 + +# By serial +mmsg dispatch toggle_monitor,serial:12345678 +``` + +--- + +## Tearing (Game Mode) + +Tearing allows games to bypass the compositor's VSync for lower latency. + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `allow_tearing` | `0` | Global tearing control: `0` (Disable), `1` (Enable), `2` (Fullscreen only). | + +## HDR +| Setting | Default | Description | +| :--- | :--- | :--- | +| `hdr_depth` | `2`| Set the hdr depth for the current display. `0` is Default, `1` is HDR8, `2` is HDR10. | + +- you should enable HDR in monitorrule first, refer to [Monitors — Monitor Rules](/docs/configuration/monitors#monitor-rules) +- you must set `env=WLR_RENDERER,vulkan` before mango starts. + +#### for example(must relogin once after setting): +```ini +env=WLR_RENDERER,vulkan +monitorrule=name:eDP-1,model:0x15F5,width:1920,height:1080,refresh:60,x:0,y:0,scale:1,vrr:0,rr:0:hdr:1 +``` + + +### Configuration + +**Enable Globally:** + +```ini +allow_tearing=1 +``` + +**Enable per Window:** + +Use a window rule to force tearing for specific games. + +```ini +windowrule=force_tearing:1,title:vkcube +``` + +### Tearing Behavior Matrix + +| `force_tearing` \ `allow_tearing` | DISABLED (0) | ENABLED (1) | FULLSCREEN_ONLY (2) | +| :--- | :--- | :--- | :--- | +| **UNSPECIFIED** (0) | Not Allowed | Follows tearing_hint | Only fullscreen follows tearing_hint | +| **ENABLED** (1) | Not Allowed | Allowed | Only fullscreen allowed | +| **DISABLED** (2) | Not Allowed | Not Allowed | Not Allowed | + +### Graphics Card Compatibility + +> **Warning:** Some graphics cards require setting the `WLR_DRM_NO_ATOMIC` environment variable before mango starts to successfully enable tearing. + +Add this to config and relogin mango: +``` +env=WLR_DRM_NO_ATOMIC,1 +``` + +--- + +## GPU Compatibility + +If mango cannot display correctly or shows a black screen, try selecting a specific GPU: + +```bash +# Use a single GPU +WLR_DRM_DEVICES=/dev/dri/card1 mango + +# Use multiple GPUs +WLR_DRM_DEVICES=/dev/dri/card0:/dev/dri/card1 mango +``` + +Some GPUs have compatibility issues with `syncobj_enable=1` — it may crash apps like `kitty` that use syncobj. Set `env=WLR_DRM_NO_ATOMIC,1` in `config.conf` and relogin to resolve this. + +--- + +## Power Management + +You can control monitor power using the `mmsg` IPC tool. +> Notice: This command does not remove the monitor, it only turns it off. +> if you want completely remove monitor, just use `wlr-randr` + +```bash +# Turn off +mmsg dispatch disable_monitor,eDP-1 + +# Turn on +mmsg dispatch enable_monitor,eDP-1 + +# Toggle +mmsg dispatch toggle_monitor,eDP-1 +``` + +You can also use `wlr-randr` for monitor management: + +```bash +# remove a monitor +wlr-randr --output eDP-1 --off + +# add a monitor +wlr-randr --output eDP-1 --on + +# Show all monitors spec +wlr-randr +``` + +--- + +## Screen Scale + +### Without Global Scale (Recommended) + +- If you do not use XWayland apps, you can use monitor rules or `wlr-randr` to set a global monitor scale. +- If you are using XWayland apps, it is not recommended to set a global monitor scale. + +You can set scale like this, for example with a 1.4 factor. + +**Dependencies:** + +```bash +yay -S xorg-xrdb +yay -S xwayland-satellite +``` + +**In config file:** + +```ini +env=QT_AUTO_SCREEN_SCALE_FACTOR,1 +env=QT_WAYLAND_FORCE_DPI,140 +``` + +**In autostart:** + +```bash +echo "Xft.dpi: 140" | xrdb -merge +gsettings set org.gnome.desktop.interface text-scaling-factor 1.4 +``` + +**Edit autostart for XWayland:** + +```bash +# Start xwayland +/usr/sbin/xwayland-satellite :11 & +# Apply scale 1.4 for xwayland +sleep 0.5s && echo "Xft.dpi: 140" | xrdb -merge +``` + +### Using xwayland-satellite to Prevent Blurry XWayland Apps + +If you use fractional scaling, you can use `xwayland-satellite` to automatically scale XWayland apps to prevent blurriness, for example with a scale of 1.4. + +**Dependencies:** + +```bash +yay -S xwayland-satellite +``` + +**In config file:** + +```ini +env=DISPLAY,:2 +exec-once=xwayland-satellite :2 +monitorrule=name:eDP-1,width:1920,height:1080,refresh:60,x:0,y:0,scale:1.4,vrr:0,rr:0 +``` + +> **Warning:** Use a `DISPLAY` value other than `:1` to avoid conflicting with mangowm. + +--- + +## Virtual Monitors + +You can create and manage virtual displays through IPC commands: + +```bash +# Create virtual output +mmsg dispatch create_virtual_output + +# Destroy all virtual outputs +mmsg dispatch destroy_all_virtual_output +``` + +You can configure virtual monitors using `wlr-randr`: + +```bash +# Show all monitors +wlr-randr + +# Configure virtual monitor +wlr-randr --output HEADLESS-1 --pos 1921,0 --scale 1 --custom-mode 1920x1080@60Hz +``` + +Virtual monitors can be used for screen sharing with tools like [Sunshine](https://github.com/LizardByte/Sunshine) and [Moonlight](https://github.com/moonlight-stream/moonlight-android), allowing other devices to act as extended monitors.