Monitors

Output rules — resolution, scale, position, and transform — with sweets.monitor.

sweets.monitor(name, { ... }) describes a physical output. Rules are optional. An output with no rule uses 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	`1.0`	Output scale, 0.1–16
`mode`	table	preferred	Resolution `{ width, height }`, 1–32767 pixels
`refresh_hz`	num	backend	Refresh rate in Hz, 0.001–1000; requires `mode`
`transform`	string	`normal`	`normal`, `90`, `180`, `270`, `flipped`, `flipped-90`, `flipped-180`, `flipped-270`
`enabled`	bool	`true`	Set `false` to start the output powered off
`adaptive_sync`	bool	off	Enable variable refresh rate (VRR / FreeSync / G-Sync)

Names must match the wlroots output name exactly, such as DP-4, HDMI-A-1, or eDP-1. Run sweetctl outputs to discover names.

Adaptive sync (VRR)

adaptive_sync = true asks the output for a variable refresh rate, so frames appear the moment they are ready. This helps gaming and video playback.

It needs support from both the display and the backend. Without it, Sweets logs a warning, leaves the mode untouched, and runs at a fixed refresh rate. If a driver accepts the setting but rejects the commit, Sweets retries once without VRR so a working mode is never lost.

Toggle it at runtime:

sweetctl output <name> adaptive_sync on|off

Read the effective state from the adaptive_sync line of sweetctl output <name>. Runtime requests are strict — an unsupported setting returns an error and leaves the active monitor rule alone.

Mode selection

When a fixed mode with the requested resolution exists, Sweets picks the closest refresh rate. If the backend advertises no fixed modes, Sweets requests a custom mode. Initial discovery can fall back to the preferred mode when nothing matches.

Reload skips the hardware transaction when monitor rules are unchanged, so an unrelated save preserves a startup fallback. Runtime IPC changes, changed rules, and reloads that replace IPC-edited state are strict: Sweets rejects an unavailable state and keeps the current one.

Sweets also exposes wlr-output-management-unstable-v1, so wlr-randr and wdisplays can change the live layout. Those changes are not written to Lua — reloading returns to the rules on this page.

Monitors

Options

Adaptive sync (VRR)

Mode selection

On this page