Rust Wallpaper MVP

Simple Windows-only wallpaper host inspired by Lively Wallpaper. The repo is now a Cargo workspace with three crates:

• wallpaper-core: WGPU-powered renderer, wallpaper session lifecycle, config primitives.
• wallpaper-host-windows: Win32 glue code that pins the render surface behind desktop icons.
• wallpaper-ui: Minimal controller binary with a console prompt + native file picker for selecting wallpapers and tweaking monitor/fit settings.

Prerequisites

• Windows 10/11
• Latest stable Rust toolchain (rustup default stable)
• Graphics drivers with WGPU/DX12 support

Building & Running

From the workspace root (the folder containing Cargo.toml with [workspace]):

# Quick check that everything compiles
cargo check

# Build UI + runtime (runtime must sit next to UI exe)
cargo build -p wallpaper-ui -p wallpaper-runtime

# Run the controller (spawns the runtime automatically if needed)
cargo run -p wallpaper-ui

Video wallpapers (MP4, etc.):

# Build with video support (needs FFmpeg DLLs – see MISSING_DLLS.md)
cargo build -p wallpaper-ui --features video -p wallpaper-runtime
cargo run -p wallpaper-ui --features video

The UI looks for wallpaper-runtime.exe in the same directory as wallpaper-ui.exe (e.g. target\debug\ or target\release\). If it’s missing, the UI will try to build the runtime with cargo build -p wallpaper-runtime for you.

Elevation: Both the UI and runtime use asInvoker in their manifests, so no admin is required for normal run. Admin is only needed to install or start the Windows service (wallpaper-runtime.exe install-service / start-service).

The first cargo run downloads dependencies (WGPU, winit, windows-rs, etc.) so the first build can take a while.

Using the Controller

Running cargo run -p wallpaper-ui launches a small Slint-powered GUI:

• Choose Image opens the native picker (via rfd) for png/jpg/bmp/gif/tga/hdr.
• Resume / Pause control the active wallpaper session.
• Monitor spin box selects the zero-based monitor; Fit mode combo maps to Fill/Fit/Stretch/Center.
• Apply Settings persists the selections to %LOCALAPPDATA%\rust_wallpaper\config.ron and restarts the wallpaper if one is running.

Wallpapers render on the target monitor using WGPU. The surface is parented to the WorkerW layer so it stays behind desktop icons and survives Explorer refreshes.

Testing Checklist

1. cargo check – validates all crates compile.
2. cargo run -p wallpaper-ui → open → pick an image → verify it appears behind icons.
3. pause then resume to ensure sessions stop/start cleanly (no orphan windows visible in the taskbar).
4. Change monitor and fit modes to confirm resize logic and config persistence work.

React UI (fastest dev): For a React-based UI instead of the Slint controller, use the HTTP API bridge and web app:

cargo build -p wallpaper-runtime -p wallpaper-api
# Ensure wallpaper-runtime.exe is next to wallpaper-api.exe (e.g. copy from target\debug\), then:
cargo run -p wallpaper-api
# In another terminal:
cd web-ui && npm install && npm run dev

Open http://localhost:5173. See web-ui/README.md for API details.

Ship together: Put the built React app in a dist/ folder next to wallpaper-api.exe; the API serves the UI at http://127.0.0.1:8765. Run wallpaper-api --app to open the UI in a desktop window (build with --features app); otherwise open the URL in a browser.

One .exe: Build with --features single-exe to embed the runtime and web UI into wallpaper-api.exe. Ship only that one executable (run cd web-ui && npm run build first). Add app to the features to get the desktop window: --features "single-exe,app".

Future work (Linux host, richer UI, video playback, etc.) can build on the abstractions introduced in wallpaper-core.