Monitors
Output rules — resolution, scale, position, and transform — with sweets.monitor.
sweets.monitor(name, { ... }) describes a physical output. Monitor rules are
optional. If an output has no rule, Sweets enables it with the backend-preferred
mode and automatic placement.
sweets.monitor("DP-4", {
position = { 0, 0 },
scale = 1.5,
mode = { 3840, 2160 },
refresh_hz = 60,
transform = "normal",
adaptive_sync = true,
})Options
| Key | Type | Default | Description |
|---|---|---|---|
position | table | auto | Layout position { x, y } in logical coordinates |
scale | num | backend | Output scale, 0.1–16 |
mode | table | preferred | Resolution { width, height }, 1–32767 pixels |
refresh_hz | num | backend | Refresh rate in Hz; requires mode |
transform | string | normal | Rotation/flip: normal, 90, 180, 270, flipped, flipped-90, flipped-180, flipped-270 |
enabled | bool | true | Set false to start the output powered off (DPMS-style) |
adaptive_sync | bool | off | Enable variable refresh rate (VRR / FreeSync / G-Sync) when the output and backend support it |
Names must match the wlroots output name exactly, such as DP-4, HDMI-A-1,
or eDP-1. Use sweetctl outputs or the compositor log to discover names.
Adaptive sync (VRR)
adaptive_sync = true asks the output to use a variable refresh rate so frames
are shown the moment they are ready — useful for gaming and smooth video. It only
takes effect when both the display and the backend support it; on hardware that
does not, Sweets logs a warning, leaves the mode untouched, and runs at the fixed
refresh rate. If a driver accepts the setting but later rejects the commit, Sweets
retries once without VRR so a working mode is never lost.
Toggle it at runtime over IPC with sweetctl output <name> adaptive_sync on|off,
and read the effective state from the adaptive_sync line of
sweetctl output <name>.
When a fixed output mode with the requested resolution exists, Sweets picks the closest matching refresh rate. If the backend advertises no fixed modes, Sweets requests a custom mode. If no advertised mode matches the requested resolution, Sweets logs an error and falls back to the preferred mode for that output.
Sweets also exposes wlr-output-management-unstable-v1, so wlr-randr and
wdisplays can change the live monitor layout. Those client-driven changes are
not written to Lua; reloading configuration returns to the rules on this page.