egui-winit: Add ViewportBuilder::with_monitor and ViewportCommand::SetMonitor

[Le-Syl21]

Summary

Adds two paired API entry-points that let an integration target a specific monitor at viewport creation time, or move an existing viewport to a different monitor at runtime, in a way that works portably on Wayland.

// At creation
ViewportBuilder::default()
    .with_inner_size([1920.0, 1080.0])
    .with_monitor(playfield_idx)         // ← new
    .with_decorations(false)

// Or at runtime
ctx.send_viewport_cmd(egui::ViewportCommand::SetMonitor(idx));

Both route through winit's Fullscreen::Borderless(Some(MonitorHandle)), which is the only portable mechanism that:

• targets a specific output on Wayland (where there is no global OuterPosition)
• avoids the Mutter race where OuterPosition is dropped before the window is mapped (X11/Wayland-Mutter)
• works the same way on Windows and macOS

with_position and with_outer_position continue to work for cases where the integration does know the absolute pixel coordinates of each monitor and is on a platform where they are honored. with_monitor is the high-level alternative when you just want "show this window on output N, borderless fullscreen."

Why this matters

Multi-monitor borderless setups (kiosks, pinball cabinets, museum installs, embedded panels) need each window to land on a specific physical display. Without with_monitor:

• On Wayland, you can't move a window to a chosen output at all — the compositor decides. There's no OuterPosition API.
• On X11/Mutter, OuterPosition is silently ignored if applied before the window is mapped, and applied a few frames late if applied after — visible flicker as the window jumps.
• Polling monitor.position() then sending OuterPosition in a retry loop is the workaround pattern, but fragile and racy.

Routing through Fullscreen::Borderless(Some(MonitorHandle)) is the same code path winit's own examples use for monitor-targeted fullscreen, just exposed at the egui ViewportBuilder level.

Implementation

• crates/egui/src/viewport.rs — adds monitor: Option<usize> to ViewportBuilder, the with_monitor(usize) builder method, and the ViewportCommand::SetMonitor(usize) variant.
• crates/egui-winit/src/lib.rs — both at viewport creation and on SetMonitor, look up the monitor by index in available_monitors() and apply Fullscreen::Borderless(Some(handle)). Index out of range is a no-op (with a log::warn!), matching how unknown values are handled elsewhere in the file.

73 lines added, 1 modified. No public API removed or changed.

Test plan

• cargo build -p egui -p egui-winit clean
• cargo clippy -p egui -p egui-winit --all-features -- -D warnings clean
• cargo fmt -p egui -p egui-winit --check clean
• Manual: tested on Linux X11 (Mutter), Linux Wayland (Mutter & KWin), Windows 11. Pinball cabinet setup with PF/BG/DMD on three different monitors — each viewport lands on the right output borderless on first frame.
• Manual: macOS — would appreciate someone testing this; I don't have hardware here. The winit code path is the same as Fullscreen::Borderless(None) which is well-exercised on macOS, so I expect it works, but cabinet/multi-monitor on macOS is niche.

Background

This is the third of three small upstream-able pieces extracted from the closed PR #8113 (viewport rotation, declined as too niche / too much surface). The rotation logic itself shipped as the standalone egui-rotate crate. The remaining two integration touch-points needed for kiosk/cabinet setups are:

• PR #8138 — App::transform_primitives + App::post_platform_output hooks (general-purpose post-tessellation / post-platform-output hooks)
• PR #8127 — Key::ShiftLeft/Right + IntlBackslash physical key variants
• This PR — with_monitor / SetMonitor

Each is independently useful. None depend on the others.

🤖 Drafted with Claude Code

[github-actions]

Preview available at https://egui-pr-preview.github.io/pr/8140-viewport-with-monitor
Note that it might take a couple seconds for the update to show up after the preview_build workflow has completed.

View snapshot changes at kitdiff

[Mingun]

Why collect?

Suggested change

	let monitors: Vec<_> = event_loop.available_monitors().collect();
	if let Some(monitor) = monitors.get(idx) {
	if let Some(monitor) = event_loop.available_monitors().nth(idx) {

[Le-Syl21]

Good catch, applied. Force-pushed with the fix — nth(idx) in the success path, available_monitors().count() only re-evaluated when we actually need it for the diagnostic.

[Le-Syl21]

@Mingun good catch, applied — force-pushed. Uses nth(idx) in the hot path; available_monitors().count() only runs when the index is out-of-range to keep the diagnostic.

[lucasmerlin]

Hmm, it's weird that the window is always placed in borderless fullscreen if this is set, what if I want to place it on a specific window with a normal fullscreen or with a certain size?

[lucasmerlin]

Looks good to me!