gardisplay

Monitor Layout

The top two-thirds of the window shows all connected monitors as scaled rectangles. Monitors are drawn proportionally to their real dimensions with labels showing the output name, resolution, and whether it's the primary display.

The layout automatically scales and centers to fit all monitors in the view area. An unsaved indicator appears in the footer when the layout has been modified.

Drag & Drop

Click and drag any monitor rectangle to reposition it. The cursor changes to indicate draggable areas and active drags. Positions are tracked in both scaled view coordinates and real pixel coordinates for RandR.

• Click a monitor to select it (highlighted border)
• Drag to move the selected monitor
• Real-world positions update in real time during the drag
• Release the mouse to finalize the new position

Snapping

When dragging, monitors snap to the edges of other monitors within a 15-pixel threshold. Alignment guides are drawn to show active snap connections.

Snapping checks both horizontal and vertical edges of all other monitors, helping you align displays precisely without gaps or overlap.

Primary Monitor

Double-click a monitor to set it as the primary display. The primary monitor is used by window managers and applications as the default display for panels, menus, and new windows.

The primary monitor is labeled in the view and persisted to the profile's primary field. The double-click threshold is 400ms.

Display Settings

Select a monitor to reveal its settings in the display panel. The panel shows the monitor name and an enabled toggle at the top, with dropdowns for resolution, refresh rate, rotation, and scale below.

Changes in the panel update the monitor view immediately. The actual display is only changed when you click Apply.

Resolution

The resolution dropdown shows all modes reported by the display driver for the selected output, sorted by pixel count (largest first).

For displays with only a single native mode (common on Apple Silicon with the appledrm driver), gardisplay generates virtual resolutions using CRTC transform scaling at 1x, 1.25x, 1.5x, and 2x. This mimics the "scaled resolutions" list in macOS display settings.

Selecting a virtual resolution automatically sets the corresponding scale factor. The native mode remains the hardware mode applied via RandR.

Refresh Rate

The refresh rate dropdown is filtered by the currently selected resolution. Only refresh rates available at that resolution are shown, sorted highest-first.

For example, a display reporting 1920x1080 at 60Hz, 120Hz, and 144Hz will show all three options when 1920x1080 is selected, but switching to 2560x1440 may show only 60Hz.

Rotation

Rotation is set via dropdown with four options:

When rotation is 90 or 270, the effective width and height are swapped in the monitor view.

Scaling

The scale dropdown offers five options: 1x, 1.25x, 1.5x, 1.75x, and 2x. Scaling is applied via RandR CRTC transforms, which adjusts the effective display area without changing the hardware mode.

For example, a 2880x1800 display at 2x scale produces an effective 1440x900 desktop area while rendering at the native resolution.

When scaling is applied, gardisplay also updates DPI settings (see DPI Scaling) so that applications render at the correct size.

Profiles

Profiles save the complete monitor layout: position, resolution, refresh rate, rotation, scale, and primary assignment for each output. Use profiles to switch between different setups without re-dragging monitors each time.

Profile Operations

When loading a profile, gardisplay checks that the profile's monitor set matches the currently connected outputs. If monitors don't match (e.g., a docked profile when undocked), positions are skipped but the primary setting is still applied.

Auto-Revert

When you apply display changes, gardisplay shows a confirmation overlay with a 15-second countdown. If you don't click Keep within that window, the display reverts to the previous working configuration.

How It Works

1. Before applying, the current RandR state is captured (positions, modes, transforms)
2. A watchdog bash script is spawned as a separate process
3. The watchdog sleeps for 15 seconds, then checks if a revert config file exists
4. If the file still exists (user didn't confirm), the watchdog runs xrandr commands to restore the previous state
5. When you click Keep, gardisplay deletes the config file, canceling the watchdog

Why a Separate Process?

If a display change causes the X connection to drop or the window to become unusable, the main gardisplay process may not be able to revert. The watchdog is an independent bash process that only depends on xrandr, so it can revert even if the main process crashes.

The revert config file is stored at $XDG_RUNTIME_DIR/gardisplay-revert.json.

DPI Scaling

When applying a layout with a non-1.0 scale factor, gardisplay updates the system DPI settings through two mechanisms:

xsettingsd (GTK applications)

gardisplay writes a config file and starts (or sends SIGHUP to) xsettingsd, setting:

• Gdk/WindowScalingFactor - Integer scale factor (rounded)
• Gdk/UnscaledDPI - Base DPI (96) in fixed-point format
• Xft/DPI - Scaled DPI in fixed-point format

xrdb (Legacy X11 applications)

The Xft.dpi resource is merged via xrdb for applications that read X resources directly.

Demo Mode

Launch with --demo to use three fake monitors instead of detecting real hardware. This is useful for UI development, testing profile management, and taking screenshots.

Demo Monitors

In demo mode, clicking Apply shows a "Demo mode - changes not applied" message. Profiles can still be saved and loaded normally.

IPC Protocol

The gardisplay-ipc crate defines request/response types for daemon communication. This protocol is planned for a future release where gardisplay can run as a background daemon controlled by a CLI tool.

Request Types

{"Detect"}                        // Re-detect connected monitors
{"Apply": {"profile": "docked"}} // Apply a named profile
{"Apply": {"profile": null}}     // Apply current layout
{"ListProfiles"}                 // List saved profile names
{"GetProfile"}                   // Get current profile name
{"SetProfile": {"name": "home"}} // Switch to a profile
{"SetBrightness": {"value": 0.8}} // Set brightness (0.0-1.0)
{"SetGamma": {"value": 1.2}}    // Set gamma (0.5-2.0)
{"NightMode": {"action": "Toggle"}} // Night mode control
{"GetState"}                     // Get full display state

Response Types

{"Ok"}
{"Error": {"message": "Monitor not found"}}
{"Profile": {"name": "default"}}
{"Profiles": {"names": ["default", "docked", "external"]}}
{"State": {
  "current_profile": "default",
  "monitors": [
    {"name": "eDP-1", "x": 0, "y": 0, "width": 2880, "height": 1800, "primary": true}
  ],
  "brightness": 1.0,
  "gamma": 1.0,
  "night_mode_active": false
}}

Events

gardisplay can emit events to notify the gar window manager of layout changes:

{"LayoutChanged": {"monitors": [
  {"name": "eDP-1", "x": 0, "y": 0, "width": 1440, "height": 900, "primary": true},
  {"name": "HDMI-1", "x": 1440, "y": 0, "width": 1920, "height": 1080, "primary": false}
]}}